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, workflows) 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>] [--no-auto-install]	Enable a method in tooling.json from local Wrekenfiles. swy add <canonical_id> is shorthand for this.
swy add workflow <canonical_id>	Install a published workflow, auto-fetching missing integrations.
swy add integration <spec>	Register an integration version in tooling.json without fetching its bundle.
swy policy add|list|remove|validate	Manage method-level guard policies in .swytchcode/integrations/policies.json, evaluated before every execution.
swy sync [project]	Re-fetch workflow/method list from the backend; updates local files without touching tooling.json. Warns on stale method hashes.
swy workflow init|validate|publish|pull	Create, validate, publish, and pull SWF v1 workflow files.

Discover

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

Run

Command	Purpose
swy demo list|stripe|fintech-compliance	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]	Connect a provider account or API key (OAuth or inline prompt), or list required providers with no argument.
swy auth status	List connected provider accounts. Aliases: list, ls.
swy auth disconnect <provider> [--local]	Disconnect a provider’s connected account.
swy auth workspace [alias-or-uuid]	Show or change which workspace this project uses. Alias: link.
swy login [--open]	Device-flow browser login; saves session to ~/.swytchcode/auth.json.
swy logout	Delete the saved session.
swy whoami	Show current auth state.

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-violation log entries (read-only history; 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 (paid plan; syncs 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, workflows) 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 workflow <canonical_id>
swy add integration <[email protected]>

• add method (or the bare add <canonical_id> shorthand) reads bundles and Wrekenfiles from .swytchcode/integrations, resolves the method/workflow 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 workflow installs a published workflow, auto-fetching any missing integration bundles.
• 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.
• --no-auto-install: Do not auto-download missing library deps for multi-library workflows.

swy policy

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

• Manages guard-policy rules in .swytchcode/integrations/policies.json - method-level rules evaluated before every exec call.
• add is interactive. remove takes a policy id. validate checks the file against the schema.
• 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, workflows.json) to compute the result.

swy list

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

• Reads only local state: .swytchcode/integrations (Wrekenfiles, methods.json, workflows.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 and published workflows via semantic search.
• 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-fetches the workflow list from the backend for each installed project (or the named one).
• Compares against local workflows.json; if changes are found, re-downloads the full bundle.
• Prints new workflows and warns about updated workflows already in tooling.json.
• Does not modify tooling.json - run swy add workflow <canonical_id> to install a new one.
• 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 workflows from backend: ...": network or auth error.

swy workflow

swy workflow init <name> [--steps a,b,c]
swy workflow validate <name>
swy workflow publish <name>
swy workflow pull <canonical_id>

• init scaffolds a minimal .workflow.yaml under .swytchcode/workflows/.
• validate checks a workflow file for duplicate step IDs, missing uses fields, unresolved state/input references, and malformed foreach blocks.
• publish validates and publishes a .workflow.yaml file to the registry. Requires login.
• pull downloads a published workflow’s YAML and writes it to .swytchcode/workflows/, updating tooling.json to point to the file.

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 and workflows 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 an actionable → Run: swy exec <id> line. 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 plan

swy plan <canonical_id>
swy plan <canonical_id> --project <name>
swy plan <canonical_id> --json

• Fetches the workflow definition from the registry and prints the ordered step list (step name, canonical ID, integration for each step).
• Does not execute anything.

Flags:

• --project <name> / -p: Project name (defaults to the canonical ID’s prefix).
• --json / -j: Output raw JSON.

swy demo / examples

swy demo list
swy demo stripe
swy demo fintech-compliance
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

• 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.
• This is log viewing only - to manage guard-policy rules, use swy policy.

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 (requires a paid plan to enable) - it is not a plain get/set key.

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.
• --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 / workspace
• swy workflow publish / pull
• swy plan

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.