# SketricGen CLI

Connect local Codex and Claude Code sessions through a stdio bridge to `https://mcp.sketricgen.ai/mcp`. Sign in in your browser; a temporary localhost listener completes authorization. The bridge uses your saved session and refreshes it automatically.

Package: `@sketric/sketricgen-mcp`. Requires Node.js 20 or later.

Install only `@sketric/sketricgen-mcp` from npm. Do not substitute a similarly named package. Hosted assistants that support remote OAuth do not need the CLI; see [native remote OAuth](https://www.sketricgen.ai/mcp.md).

## Connect your agent

```bash
npm install -g @sketric/sketricgen-mcp
sketricgen connect --agent codex
```

For Claude Code, use `sketricgen connect --agent claude-code`.

The command configures only SketricGen, opens browser sign-in when needed, waits for project consent and the localhost callback, then verifies initialization, tool discovery, `whoami`, and `list_agents`. Reload your agent session afterward. Verification does not change resources or run agents.

Setup pins the absolute Node executable and installed bridge path so the connection survives host restarts. Use a stable global install. An ephemeral `npx` install is unsuitable for persisted bridge configuration. Re-run setup after changing the Node installation path.

## Separate commands

```bash
sketricgen setup --agent codex --dry-run
sketricgen setup --agent codex
sketricgen auth login
sketricgen doctor
sketricgen tools
sketricgen auth status
sketricgen auth logout
```

`setup` preserves other MCP servers. If a different SketricGen entry exists, it stops and tells you how to inspect and migrate that entry. Configuration alone does not confirm authorization.

`auth login` requests fresh project consent. `auth status` checks local credentials without printing secrets or contacting the server. `doctor` verifies remote access. `tools` lists discovered tool names. `mcp` runs the stdio bridge and reserves stdout for MCP messages.

## Update

```bash
npm install -g @sketric/sketricgen-mcp@latest
sketricgen doctor
```

Restart your agent after updating. New SketricGen tools appear without a package update because the bridge forwards the live server tools.

## Sign-in and storage

Login uses authorization code with PKCE, dynamic client registration, OAuth discovery, and random state. The callback listener binds only to `127.0.0.1` on an available port, accepts one matching callback, and shuts down afterward. Finish browser sign-in within five minutes.

In the browser you sign in on the SketricGen sign-in page (email and password, or Google), then choose one or more projects from one Teamspace and approve or deny access. Keep the command running until the browser returns you to the local confirmation page. If you choose **Deny**, nothing is shared, the page says access was denied, and the command exits with an error; run `sketricgen auth login` again to retry. If the command already stopped (for example it timed out or was interrupted), the browser cannot reach the local page and shows a connection error instead.

The OS credential store holds an encryption key. The session is stored as authenticated ciphertext in a private configuration directory. Refresh operations are serialized across CLI and bridge processes so rotating refresh tokens are not used concurrently.

If the OS store is unavailable or locked, login fails with an actionable error. There is no automatic plaintext fallback. On Linux the CLI requires a Secret Service (GNOME Keyring, KWallet, or similar) and never uses the in-memory kernel keyring, which is cleared on reboot. On a private computer, you can explicitly choose file storage:

```bash
sketricgen auth login --credential-store file
```

This stores plaintext credentials protected by directory mode 700 and file mode 600 on Unix. On Windows, keep the directory protected by your user account's ACLs. Prefer the OS store.

Read-only consent:

```bash
sketricgen auth login --read-only
```

This requests the server's read scope and `offline_access`. Standard login requests SketricGen's advertised scopes, including write and offline access. A write scope does not override your live project role.

If browser launch fails, open the printed URL on the same computer. `--no-browser` prints the link without opening it. This callback flow requires a local browser; it does not implement device-code login for a remote headless machine.

## Logout

`auth logout` revokes the saved refresh grant before removing local credentials. If revocation fails, it retains credentials so logout can be retried.

`auth logout --local-only` explicitly forgets local credentials without revoking the grant. It also works when the OS store is unavailable. Logout does not remove an API key supplied through the environment.

## Environment

| Variable | Purpose |
| --- | --- |
| `SKETRICGEN_MCP_URL` | Override the remote endpoint. HTTPS required except for HTTP loopback development. |
| `SKETRICGEN_CONFIG_DIR` | Override the private session directory. Default: `$XDG_CONFIG_HOME/sketricgen`, or `~/.config/sketricgen`. |
| `SKETRICGEN_API_KEY` | Explicit API-key authentication for automation. Overrides saved OAuth. Requires Manage resources access. |

These are CLI variables, not browser configuration or Next.js secrets. Keep credentials out of chat, command arguments, and tracked host settings. Discovery and token requests are restricted to the configured server's origin, matching SketricGen's OAuth facade.

For another local host, configure a stdio server using the absolute Node executable and installed `sketricgen-mcp.js` path shown by `setup --dry-run`. Hosted assistants use [remote OAuth](https://www.sketricgen.ai/mcp.md).