# 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= ] [--mode= ] [--non-interactive]` | Initialize `.swytchcode/`, create `tooling.json`, install editor rules and register the MCP server. |
| `swy get [--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 ] [--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 ` | 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 [--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 [--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 ` | 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 ` | 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 ` / `set ` | 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](/cli/exec/) for the full input/output contract, exit codes, and error handling.

## swy init

```bash
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

```bash
swy get
```

- Fetches integration bundles (Wrekenfiles, methods, workflows) for ` ` from the registry.
- Writes them under `.swytchcode/integrations/ / / /`.
- Updates `manifest.json` with endpoints and counts.
- Does **not** modify `tooling.json`; use `add` to enable tools.

## swy bootstrap

```bash
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

```bash
swy add <canonical_id>
swy add method <canonical_id>
swy add method --all
swy add workflow <canonical_id>
swy add integration
```

- **`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 `project@library.version` to disambiguate.

**Flags (`add method`):**
- `--all `: 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

```bash
swy policy add
swy policy list [--json]
swy policy remove
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](/reference/mcp-reference/) and the System commands table above.

## swy info

```bash
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

```bash
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

```bash
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](https://www.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 `: 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

```bash
swy sync
swy sync
```

- 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 "`: no projects installed.
- `"fetch workflows from backend: ..."`: network or auth error.

## swy workflow

```bash
swy workflow init [--steps a,b,c]
swy workflow validate
swy workflow publish
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

```bash
swy discover " "
swy discover " " --project
swy discover " " --library
swy discover " " --top 10 --json
```

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

**Flags:**
- `--project ` / `-p`: Scope to a specific project.
- `--library ` / `-l`: Scope to a specific library within a project.
- `--top ` / `-n`: Number of results (default: 5).
- `--select ` / `-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 ` line. Pass `--json` to suppress the human-formatted hints (recommended for agents).

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

## swy plan

```bash
swy plan <canonical_id>
swy plan <canonical_id> --project
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 ` / `-p`: Project name (defaults to the canonical ID's prefix).
- `--json` / `-j`: Output raw JSON.

## swy demo / examples

```bash
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

```bash
swy audit
swy audit network [--json] [-n N]
swy audit network --info
swy audit policy [--json] [-n N]
swy audit policy --info
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

```bash
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

```bash
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](/cli/mcp/) and the [MCP Reference](/reference/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.