Command reference

This document summarizes the Swytchcode CLI surface, with a focus on inputs, outputs, and behavior. The CLI is also available as the shorter alias swy (e.g. swy list, swy exec).

Commands at a glance

Project setup

Command	Purpose
swy init [--editor=<name>] [--mode=<mode>] [--non-interactive]	Initialize .swytchcode/, create tooling.json, install editor rules and register the MCP server.
swy get <project> [--non-interactive] [--yes]	Fetch integration bundles (Wrekenfiles, methods) for a project; does not modify tooling.json.
swy bootstrap	Fetch all integrations declared in tooling.json.integrations that aren’t already installed (CI-friendly).
swy add method [spec] <canonical_id> [--all <project>]	Enable a method in tooling.json from local Wrekenfiles. swy add <canonical_id> is shorthand for this.
swy add integration <spec>	Register an integration version in tooling.json without fetching its bundle.
swy policy add|list|remove|validate|state	Manage guard policies in .swytchcode/integrations/policies.json, evaluated for every execution.
swy sync [project]	Re-fetch installed integration bundles from the backend; updates local files without touching tooling.json. Warns on stale method hashes.

Discover

Command	Purpose
swy discover <intent> [--project] [--library] [--top N] [--select] [--json]	Semantic search: find methods by natural-language description.
swy info <canonical_id> [--json]	Show detailed info about a tool (resolved inputs/output).
swy list [methods|integrations|tooling] [pattern] [--json]	List tools and integrations from local state only (no registry calls).
swy search [keyword] [--limit N] [--all] [--refresh] [--json]	Search the remote registry for integrations. Results cached 1 hour.

Run

Command	Purpose
swy demo list|stripe	Run a demo integration - no setup or API keys required.
swy examples list	Interactively choose an example and framework, download a ready-to-run project.
swy exec [canonical_id|intent] [flags]	Single execution path - canonical ID for direct execution; intent string (no dot) for semantic search with picker. Accepts CLI args or JSON stdin.

Account

Command	Purpose
swy auth connect [provider] [--tenant <id>] [--json]	Connect a provider account or API key (OAuth or inline prompt), or list required providers with no argument. --tenant connects one end user of your app; --json prints the result (for OAuth, the connect link) instead of opening a browser. See Multi-tenant apps.
swy auth status [--tenant <id>]	List connected provider accounts, or one end user’s with --tenant. Aliases: list, ls.
swy auth disconnect <provider> [--local] [--tenant <id>]	Disconnect a provider’s connected account, or one end user’s with --tenant.
swy login [--open]	Device-flow browser login; saves session to ~/.swytchcode/auth.json. First 2 live commands don’t require sign-in.
swy logout	Delete the saved session.
swy whoami	Show current auth state.
swy workspace	Show this project’s workspace and list your others.
swy workspace use <name> [--create]	Use another of your workspaces in this project (--create creates it). Saved in tooling.json.

System

Command	Purpose
swy audit	Interactive: choose network / policy / stats to view (non-interactively, shows help).
swy audit network [--json] [-n N]	Recent outbound network calls: host, method, status, duration - each with a unique id.
swy audit network --info <id>	Full detail for one network call.
swy audit policy [--json] [-n N]	Recent policy decisions: blocked, held, changed, hidden, or monitored calls (manage rules via swy policy).
swy audit policy --info <id>	Full detail for one policy violation.
swy audit stats	Local execution history: total runs, success rate, last run, top provider.
swy audit clear	Delete all local audit files.
swy config	Show the current value of every config key and how to change it.
swy config get <key> / set <key> <value>	Manage config. Keys: telemetry_enabled (cloud_sync_enabled is managed via config cloud).
swy config telemetry enable|disable|status	Opt in/out of anonymous usage telemetry, product analytics, and crash-report consent (single switch for all of it).
swy config cloud enable|disable|status	Cloud audit trail sync (optional; daily background upload of metadata, never payloads).
swy doctor [--network] [--json]	Local diagnostics: tooling, bundles, auth, permissions, secrets; --network checks endpoint reachability.
swy mcp serve [--profile agent|full] [--transport stdio|http] [--port N] [-d] [--claude]	Start the MCP server.
swy mcp status / swy mcp stop	Daemon status / stop.
swy mcp token [--rotate]	Print the MCP HTTP bearer token.

swy exec

See the exec reference for the full input/output contract, exit codes, and error handling.

swy init

swy init
swy init --editor=cursor --mode=production --non-interactive

• Creates .swytchcode/ and .swytchcode/integrations/.
• Writes tooling.json with version, mode (production or sandbox), and empty integrations/tools maps.
• Installs editor rule templates and registers the MCP server as a stdio subprocess (command: swytchcode, args: [mcp, serve]) - no daemon and no manual URL/port setup required for any editor:
  • cursor -> .cursor/rules/swytchcode.mdc; merges the stdio entry into ~/.cursor/mcp.json
  • claude -> CLAUDE.md; registers via claude mcp add (requires the claude CLI on PATH) so Claude Code writes it to whichever file it actually reads
  • codex -> AGENTS.md; merges into ~/.codex/config.toml
  • copilot -> .github/copilot-instructions.md; merges into .vscode/mcp.json
  • gemini -> GEMINI.md; merges into ~/.gemini/settings.json
  • hermes -> AGENTS.md (shared with codex); merges into ~/.hermes/config.yaml
  • openclaw -> OPENCLAW.md; merges into ~/.openclaw/settings.json
  • windsurf -> WINDSURF.md; merges into ~/.codeium/windsurf/mcp_config.json
• Re-running init with a different editor warns about orphaned files from the previous choice.

swy get

swy get <project>

• Fetches integration bundles (Wrekenfiles, methods) for <project> from the registry.
• Writes them under .swytchcode/integrations/<project>/<library>/<version>/.
• Updates manifest.json with endpoints and counts.
• Does not modify tooling.json; use add to enable tools.

swy bootstrap

swy bootstrap

• Reads tooling.json.integrations.
• For each project.library with a version, ensures corresponding bundles are fetched and on disk, and updates manifest.json.

Intended for CI to keep .swytchcode/integrations in sync with tooling.json.

swy add

swy add <canonical_id>
swy add method <[email protected]> <canonical_id>
swy add method --all <project>
swy add integration <[email protected]>

• add method (or the bare add <canonical_id> shorthand) reads bundles and Wrekenfiles from .swytchcode/integrations, resolves the method and its STRUCTs into concrete input/output schemas, and adds an entry in tooling.json.tools. Stores a method_hash (SHA-256 of the Wrekenfile entry) to enable stale detection in sync.
• add integration registers an integration version in tooling.json explicitly, without fetching its bundle.

If the canonical ID exists in multiple integrations, add method may require an explicit [email protected] to disambiguate.

Flags (add method):

• --all <project>: Add all methods for the project. Skips already-present IDs.

swy policy

swy policy add [flags]
swy policy list [--json]
swy policy remove <id>
swy policy validate
swy policy state [<id>] [--json] [--reset]

• Manages guard-policy rules in .swytchcode/integrations/policies.json, evaluated for every exec call.
• add is interactive, or non-interactive with --non-interactive and flags: --name, --id, --target, --field, --operator, --value, --action, --message, and for version-2 files --list, --ignore-case, --transform, --quantifier, --mode, --hint. See Add a policy.
• remove takes a policy id.
• validate checks the file against the schema and the installed tools’ input schemas, then runs the tests written in it. Exits with code 1 on an error or a failing test.
• state shows what rate, sum, repeat, called_before, and returned_by conditions have counted for this project on this machine, and approvals that can still be reused. --reset clears them (for one policy when an id is given).
• swy sync, swy get, and swy add print a warning when a policy uses a field an installed tool no longer has.
• Past violations of these rules are viewable (read-only) via swy audit policy - see MCP Reference and the System commands table above.

swy info

swy info <canonical_id>

• Shows rich information for a tool: source integration, summary/description, and resolved input/output schemas (STRUCTs expanded).
• Uses both tooling.json and integration artifacts (wrekenfile.yaml, methods.json) to compute the result.

swy list

swy list
swy list methods [pattern]
swy list integrations [pattern]
swy list tooling [pattern]

• Reads only local state: .swytchcode/integrations (Wrekenfiles, methods.json).
• tooling filter reads from tooling.json and shows only what has been explicitly enabled via swy add. Use this to verify a canonical ID is registered before generating execution code.
• --json returns a machine-readable result: arrays of { "canonical_id": "...", "integration": "project.library@version" }.

swy search

swy search
swy search stripe
swy search stripe --limit 5
swy search --all --json
swy search --refresh

• Contacts the registry. Without a keyword, lists all available integrations; with a keyword, returns matching integrations. To find methods by what they do, use swy discover.
• Browse the full, up-to-date list of supported APIs at swytchcode.com/apis.
• Results are cached for 1 hour; subsequent searches in the same session are instant.
• Shows 10 results by default; prints N more - use --all when there are more.
• Does not modify local state; use get / bootstrap to fetch bundles.

Flags:

• --limit <n>: Maximum results to show (default: 10).
• --all: Show all matching results.
• --refresh: Bypass cache and fetch fresh results from the registry.
• --json: Output as JSON array (always returns the full matched list, no truncation).

swy sync

swy sync
swy sync <project>

• Re-downloads the integration bundles from the backend for each installed project (or the named one).
• Does not modify tooling.json.
• After bundle refresh, re-hashes all method entries against stored method_hash values in tooling.json. Warns if any differ: ⚠ method X has changed: run swy add X to refresh tooling.json.

Error messages:

• "no integrations found: run swy get <project>": no projects installed.
• "fetch provider bundles: ...": network or auth error.

swy discover

swy discover "<intent>"
swy discover "<intent>" --project <name>
swy discover "<intent>" --library <name>
swy discover "<intent>" --top 10 --json

• Sends a semantic search query to the backend.
• Returns ranked methods matching the plain-English intent.

Flags:

• --project <name> / -p: Scope to a specific project.
• --library <name> / -l: Scope to a specific library within a project.
• --top <n> / -n: Number of results (default: 5).
• --select <index-or-id> / -s: Headless selection for agents - bypasses the interactive prompt.
• --json / -j: Output raw JSON.

Output: Each result shows canonical ID, type, integration, confidence score, and a swytchcode exec <id> line to run it. Pass --json to suppress the human-formatted hints (recommended for agents).

swy exec "<intent>" calls the same backend automatically and shows an interactive picker on TTY, so discover is optional for humans.

swy demo / examples

swy demo list
swy demo stripe
swy examples list

• demo runs a bundled demo integration with simulated responses - no project setup or API keys required.
• examples interactively downloads a ready-to-run example project.

swy audit

swy audit
swy audit network [--json] [-n N]
swy audit network --info <id>
swy audit policy [--json] [-n N]
swy audit policy --info <id>
swy audit stats
swy audit clear
swy audit <network|policy|stats> --tenant <id>

• Views local execution data stored in ~/.swytchcode/audit/: outbound network activity, policy-violation history, and execution stats.
• Bare swy audit in an interactive terminal prompts for which of network / policy / stats to view; non-interactively it prints help.
• Every network call and policy-violation entry has a unique id (nw_... / pol_...) for info lookups.
• --tenant <id> shows only entries for one end user of your app (see Multi-tenant apps).
• This is log viewing only - to manage guard-policy rules, use swy policy. The local record is readable only by you; you don’t need to sign in to see it.

swy config

swy config
swy config get telemetry_enabled
swy config set telemetry_enabled true
swy config telemetry enable|disable|status
swy config cloud enable|disable|status

• Bare swy config prints the current value of every key along with how to change it.
• telemetry_enabled is the single switch for anonymous usage telemetry, product analytics, and crash-report consent.
• cloud_sync_enabled is managed only via config cloud - it is not a plain get/set key. History is uploaded once a day in the background and never interrupts commands.

swy doctor

swy doctor
swy doctor --network
swy doctor --json

• Checks tooling.json, installed integration bundles, manifest.json, execution base URLs, and auth-related environment.
• Warns about each provider whose base URL is not set for the mode its tools run in. A warning doesn’t change the exit code.
• --network also shows every network endpoint the CLI may contact and its current status.
• Exits 1 if any check reports an error (useful in CI).

MCP commands

See MCP server and the MCP Reference for server setup, profiles, tool tables, and editor integration.

Auth and backend-related commands

These commands use SWYTCHCODE_TOKEN or ~/.swytchcode/auth.json for auth:

• swy login
• swy logout
• swy whoami
• swy auth connect / status / disconnect
• swy workspace / workspace use

See backend-specific docs for exact payloads and behavior. From the CLI’s perspective, they:

• Resolve project UUIDs and tokens via internal/auth.
• Call backend endpoints for account/project/introspection and plan/usage info.
• Exit with non-zero codes on auth/network/server errors, printing clear messages on stderr.

Setting SWYTCHCODE_TOKEN

The CLI reads the token only from the process environment and does not load .env files.

Mac / Linux

Goal	Command
Current session only	export SWYTCHCODE_TOKEN=your_token_here
Permanent (Zsh, default on macOS)	echo 'export SWYTCHCODE_TOKEN=your_token_here' >> ~/.zshrc && source ~/.zshrc
Permanent (Bash)	echo 'export SWYTCHCODE_TOKEN=your_token_here' >> ~/.bashrc && source ~/.bashrc
Per-directory (direnv)	Add export SWYTCHCODE_TOKEN=your_token_here to .envrc, then direnv allow .
From a .env file (one-off)	set -a && source .env && set +a then run swy

Windows

Goal	Command
Current PowerShell session	$env:SWYTCHCODE_TOKEN = "your_token_here"
Permanent (PowerShell, user-level)	[System.Environment]::SetEnvironmentVariable("SWYTCHCODE_TOKEN","your_token_here","User")
Permanent (cmd / setx, user-level)	setx SWYTCHCODE_TOKEN "your_token_here"
Via GUI	System Properties > Advanced > Environment Variables > User variables > New

Note: After setx or the GUI method, open a new terminal window for the change to take effect.

MCP in the IDE

Configure the MCP server’s env block with SWYTCHCODE_TOKEN so the server process inherits it. If you start the MCP server from a terminal, export the token first.

CI/CD

Define SWYTCHCODE_TOKEN as a secret or CI variable so the job environment has it.

Telemetry

Usage events are sent only when swy config telemetry is enabled and you’re authenticated (via swy login or SWYTCHCODE_TOKEN). This single setting also covers product analytics and crash-report consent - there is no separate opt-in for those. When telemetry is off or you have no auth, no events are sent.