> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Terminal

<Note>The Stigg AI Terminal is currently in **public beta**. Feedback and bug reports are welcome.</Note>

The AI Terminal is a one-command setup tool that wires Stigg into your AI coding assistant. It signs you in, writes the Stigg [MCP server](/api-and-sdks/mcp-server) into each client's config, and installs the Stigg [agent skills](/api-and-sdks/agent-skills). It automates the same setup you'd otherwise do by hand, end to end.

```bash theme={null}
npx @stigg/terminal
```

Run it with no arguments for an interactive, full-screen setup, or in `--headless` mode so an AI agent or CI job can run it for you. Supported clients: **Claude Code, Cursor, VS Code, Codex, and Claude Desktop**.

***

## Requirements & install

Requires **Node.js 22+**. No install needed: run it directly with `npx`, or install globally to get the `stiggt` command:

<CodeGroup>
  ```bash npx theme={null}
  npx @stigg/terminal
  ```

  ```bash Global install theme={null}
  npm i -g @stigg/terminal
  stiggt
  ```
</CodeGroup>

***

## Two ways to run it

The AI Terminal works the same whether a human drives it or an agent does. The difference is interactive vs. non-interactive.

**Interactive (you, in a terminal).** Run `npx @stigg/terminal` with no arguments. It opens a full-screen TUI that signs you in through the browser, lets you pick the account, environment, and API key, and choose which clients to configure, then writes everything and shows a summary. When setup succeeds it also offers to launch your coding agent (Claude Code, Codex, or Cursor) right there, seeded with a starter prompt so you can begin building immediately. Best for first-time, hands-on setup.

**Headless (an AI agent or CI).** Pass `--headless` (or use the `mcp add` / `skills add` subcommands) for a fully non-interactive run, with optional JSON output. Best when you want your coding agent to set itself up, or when running in a pipeline. See [Headless usage](#headless-usage).

<Note>
  Interactive `init` requires a real terminal (TTY). In a non-interactive context, pass `--headless`; otherwise the command exits with an error telling you to.
</Note>

***

## Command reference

Run `stiggt <command> --help` for the flags on any command.

### `stiggt`

With no arguments in an interactive terminal, launches the setup TUI: sign in → pick account / environment / API key → pick clients → write MCP and install skills → summary. When setup succeeds, it offers to launch your coding agent (Claude Code, Codex, or Cursor), seeded with a starter prompt. With no TTY, it prints help instead.

### `stiggt init`

Runs the full setup: authenticate, write MCP, install skills. Interactive by default; add `--headless` to run without the TUI. In headless mode it runs in [two phases](#the-two-phase-init).

| Flag                     | Description                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `--headless`             | Run without the interactive TUI (non-interactive).                                                            |
| `--force-login`          | Re-authenticate even if a valid session is cached.                                                            |
| `--callback-port <port>` | Loopback port for the OAuth callback (overrides `STIGG_CALLBACK_PORT`).                                       |
| `--account-id <id>`      | Phase 2: account ID from the phase 1 listing.                                                                 |
| `--environment-id <id>`  | Phase 2: environment ID from the phase 1 listing.                                                             |
| `--api-key-id <id>`      | Phase 2: API key ID from the phase 1 listing.                                                                 |
| `-c, --client <id>`      | Limit to specific client(s); repeatable. Default: the host agent if detected, otherwise all detected clients. |
| `--all`                  | Target every detected client (overrides the host-agent default).                                              |
| `--no-skills`            | Skip installing skills (skills install by default).                                                           |
| `--json`                 | Emit a single JSON object on stdout instead of human-readable text.                                           |

### `stiggt mcp add`

Writes the Stigg MCP entry into one or more client configs, without authenticating or installing skills. Requires an API key (`--api-key` or `STIGG_API_KEY`) and one of `--client` / `--all`.

| Flag                | Description                                       |
| ------------------- | ------------------------------------------------- |
| `--api-key <value>` | Stigg API key (or set `STIGG_API_KEY`). Required. |
| `-c, --client <id>` | Target client; repeatable.                        |
| `--all`             | Target every detected client.                     |
| `--json`            | JSON output.                                      |

### `stiggt skills add`

Installs the Stigg agent skills for one or more clients, without touching MCP config. No API key required. Requires one of `--client` / `--all`.

| Flag                | Description                   |
| ------------------- | ----------------------------- |
| `-c, --client <id>` | Target client; repeatable.    |
| `--all`             | Target every detected client. |
| `--json`            | JSON output.                  |

### `stiggt env`

Opens an interactive picker to switch the active Stigg environment, then rewrites the MCP config for the clients in your saved setup.

### `stiggt dash`

Opens the Stigg dashboard in your default browser.

### Global flags

| Flag        | Description                                                          |
| ----------- | -------------------------------------------------------------------- |
| `--help`    | Show usage for the program or a command (`stiggt <command> --help`). |
| `--version` | Print the version.                                                   |

### Clients

Pass these IDs to `-c, --client`. A client must be installed and detected to be configured, and `--client` and `--all` are mutually exclusive.

| Client         | ID               | Platforms             |
| -------------- | ---------------- | --------------------- |
| Claude Code    | `claude-code`    | macOS, Linux, Windows |
| Cursor         | `cursor`         | macOS, Windows        |
| Claude Desktop | `claude-desktop` | macOS, Windows        |
| VS Code        | `vscode`         | macOS, Linux, Windows |
| Codex          | `codex`          | macOS, Linux, Windows |

***

## What it writes

For each selected client, the AI Terminal adds a server named `stigg` pointing at the Stigg MCP server (`https://mcp.stigg.io`), authenticated with your environment API key via the `X-API-KEY` header. Existing config files are **merged, not overwritten**, and backed up to `<path>.bak.<timestamp>` before any change.

<Tabs>
  <Tab title="Claude Code">
    Uses the `claude` CLI (no file is edited). The server is added at user scope, idempotently, so re-running removes and re-adds it:

    ```bash theme={null}
    claude mcp add --scope user --transport http stigg https://mcp.stigg.io \
      --header "X-API-KEY: <YOUR_API_KEY>"
    ```
  </Tab>

  <Tab title="Cursor">
    Writes `~/.cursor/mcp.json` (HTTP transport):

    ```json ~/.cursor/mcp.json theme={null}
    {
      "mcpServers": {
        "stigg": {
          "url": "https://mcp.stigg.io",
          "headers": { "X-API-KEY": "<YOUR_API_KEY>" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    If the `code` CLI is on your `PATH`, runs `code --add-mcp`; otherwise writes the MCP user-config file directly:

    * **macOS:** `~/Library/Application Support/Code/User/mcp.json`
    * **Windows:** `%APPDATA%\Code\User\mcp.json`
    * **Linux:** `~/.config/Code/User/mcp.json`

    ```json mcp.json theme={null}
    {
      "servers": {
        "stigg": {
          "type": "http",
          "url": "https://mcp.stigg.io",
          "headers": { "X-API-KEY": "<YOUR_API_KEY>" }
        }
      }
    }
    ```

    VS Code uses the `servers` key (not `mcpServers`).
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop only speaks stdio, so the Terminal wraps the HTTP server with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). Writes:

    * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

    ```json claude_desktop_config.json theme={null}
    {
      "mcpServers": {
        "stigg": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://mcp.stigg.io", "--header", "X-API-KEY:${STIGG_API_KEY}"],
          "env": { "STIGG_API_KEY": "<YOUR_API_KEY>" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    Also stdio via `mcp-remote`. Writes `~/.codex/config.toml`:

    ```toml ~/.codex/config.toml theme={null}
    [mcp_servers.stigg]
    command = "npx"
    args = ["-y", "mcp-remote@latest", "https://mcp.stigg.io", "--header", "X-API-KEY:${STIGG_API_KEY}"]

    [mcp_servers.stigg.env]
    STIGG_API_KEY = "<YOUR_API_KEY>"
    ```
  </Tab>
</Tabs>

After writing, **restart the client** to load the new server.

<Tip>
  The config paths above can be relocated with environment variables (`STIGG_CURSOR_CONFIG`, `STIGG_VSCODE_CONFIG`, `STIGG_CLAUDE_DESKTOP_CONFIG`, `STIGG_CODEX_CONFIG`), which is useful for testing or non-standard installs.
</Tip>

***

## Agent skills it installs

Unless you pass `--no-skills`, the Terminal also installs the [Stigg agent skills](/api-and-sdks/agent-skills): domain knowledge that helps your assistant use the MCP tools well. It uses the right channel per client:

* **Claude Code** registers the marketplace and installs the plugin:

  ```bash theme={null}
  claude plugin marketplace add stiggio/skills
  claude plugin install stigg@stigg-marketplace
  ```

* **Other clients** install via the agent-skills CLI:

  ```bash theme={null}
  npx -y skills add stiggio/skills --all
  ```

Skills install is best-effort: if a step fails, the rest of setup still completes and the failure is reported.

***

## Headless usage

`--headless` makes `init` fully non-interactive (no TUI, no prompts), so an AI agent or CI pipeline can run it. Add `--json` for machine-readable output.

### Let your coding agent set itself up

If you're already working inside an AI coding assistant, just ask it to run the Terminal. It detects its host (**Claude Code, Cursor, Codex, and VS Code are auto-detected** via environment variables the host sets) and configures that client by default:

> *"Connect this project to Stigg: run `npx @stigg/terminal init --headless` to install the MCP server and skills, then confirm it worked by listing my Stigg plans."*

Override the target with `-c/--client` or `--all`. To force or disable detection, set `STIGG_HOST_AGENT` (a client ID, or `none`).

### The two-phase init

Because an account can have multiple environments and API keys, headless `init` runs in two phases. (If you have exactly one account, one environment, and one API key, it auto-selects them and completes in a single run.)

<Steps>
  <Step title="Phase 1: authenticate and list">
    Run `init --headless` with no ID flags. It reuses your cached session (or opens a browser to sign in the first time), then lists your accounts, environments, and API keys.

    ```bash theme={null}
    npx @stigg/terminal init --headless --json
    ```

    With `--json`, you get a structured listing to parse:

    ```json theme={null}
    {
      "user": "you@example.com",
      "accounts": [
        {
          "id": "<account-id>",
          "name": "Acme",
          "environments": [
            {
              "id": "<environment-id>",
              "name": "Production",
              "slug": "production",
              "apiKeys": [
                {
                  "id": "<api-key-id>",
                  "name": "Server",
                  "lastFour": "ab12",
                  "keyType": "SERVER",
                  "createdAt": "2026-01-01T00:00:00.000Z"
                }
              ]
            }
          ]
        }
      ],
      "nextStep": "..."
    }
    ```
  </Step>

  <Step title="Phase 2: provision">
    Pass the chosen IDs back; all three are required together. The Terminal writes the MCP config and installs skills for the selected clients:

    ```bash theme={null}
    npx @stigg/terminal init --headless \
      --account-id <account-id> \
      --environment-id <environment-id> \
      --api-key-id <api-key-id> \
      --all
    ```
  </Step>
</Steps>

On success, `init --json` emits a single object describing what happened:

```json theme={null}
{
  "ok": true,
  "writes": [{ "client": "claude-code", "path": "claude mcp add", "written": true }],
  "skipped": [],
  "skillsInstall": { "ok": true },
  "setupPath": "~/.config/stigg/setup.json",
  "hostAgent": { "id": "claude-code", "name": "Claude Code" },
  "restartHint": "Restart Claude Code (/exit + run `claude` again) to load Stigg MCP into your next session.",
  "nextStepPrompt": "..."
}
```

### No-browser path (CI)

The simplest non-interactive setup skips OAuth entirely: create an API key in the Stigg dashboard, then write the MCP config (and optionally skills) directly. No TTY and no browser required, which is ideal for CI, Dockerfiles, and provisioning scripts.

```bash theme={null}
export STIGG_API_KEY=<YOUR_API_KEY>
npx @stigg/terminal mcp add --all --json
npx @stigg/terminal skills add --all
```

### Exit codes

| Code | Meaning                                                                  |
| ---- | ------------------------------------------------------------------------ |
| `0`  | Success                                                                  |
| `1`  | Runtime error or partial failure (e.g. some clients couldn't be written) |
| `2`  | Invalid options, or a target config file was malformed                   |

***

## Authentication & stored files

Interactive and phase-1 headless runs sign you in through your browser. The Terminal starts a local listener on `http://127.0.0.1:57166/callback` to receive the redirect; if that port is taken or isn't whitelisted, pass a different one with `--callback-port` (or set `STIGG_CALLBACK_PORT`). If the browser doesn't open automatically, the sign-in URL is printed so you can open it manually.

Your session is cached so you don't sign in every time:

| File                               | Purpose                                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------------------------- |
| `~/.config/stigg/credentials.json` | Cached auth session, reused until it expires.                                                   |
| `~/.config/stigg/setup.json`       | Your last completed setup: account, environment, and configured clients (used by `stiggt env`). |

Both honor `$XDG_CONFIG_HOME` and are written with restrictive (owner-only) permissions. Pass `--force-login` to re-authenticate even when a valid session is cached. `mcp add` and `skills add` don't sign in at all; `mcp add` takes the API key directly.

***

## Environment variables

| Variable              | Description                                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `STIGG_API_KEY`       | API key used by `mcp add` (and the no-browser path) when `--api-key` isn't passed.                                                |
| `STIGG_CALLBACK_PORT` | Override the default OAuth callback port (`57166`).                                                                               |
| `STIGG_HOST_AGENT`    | Force which host agent is assumed (`claude-code`, `cursor`, `vscode`, `codex`, `claude-desktop`), or `none` to disable detection. |

***

## Security

<Warning>
  The MCP server the Terminal installs lets your AI agent act on your Stigg environment, including creating customers, provisioning subscriptions, and modifying your catalog. **Connect a sandbox environment for development and testing; only connect production when you have a clear need and understand the risks.**
</Warning>

* **Use scoped API keys when available.** Create a dedicated, least-privilege key per client rather than reusing a full-access key (scoped keys are available on the Scale plan).
* **Keys are environment-bound.** The key you select determines exactly which Stigg environment the agent operates on.
* **Never commit API keys** or share them in chat. Treat them like passwords.

See [MCP server → Security](/api-and-sdks/mcp-server#security) for the full guidance.

***

<CardGroup cols={2}>
  <Card title="MCP Server" icon="robot" href="/api-and-sdks/mcp-server">
    What the Terminal connects you to, and how to set it up by hand.
  </Card>

  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/api-and-sdks/agent-skills">
    The domain knowledge the Terminal installs. See all skills and manual install steps.
  </Card>
</CardGroup>

<Card title="CLI vs MCP server" icon="arrow-right-arrow-left" href="/api-and-sdks/cli-vs-mcp">
  Not sure which tool to use? See the side-by-side comparison.
</Card>