# CLI Configuration

<!-- FLY-1138: moved here from AGENTS.md ("Dev Override: skipPaths" and
     "Credentials"), which keeps one-line pointers. Setup detail is read on
     demand; the never-commit-secrets guardrail stays eager in Hard Rules. -->

## Dev Override: skipPaths

To prevent `flydocs update` from overwriting paths you're actively developing,
add `artifactOverrides.skipPaths` to `.flydocs/config.json`:

```json
{
  "artifactOverrides": {
    "skipPaths": [".claude/skills/flydocs-workflow/"]
  }
}
```

Paths listed here are excluded from artifact sync. This is CLI-local only —
not stored on the server, not visible in the portal, and preserved across syncs.

## Credentials

Cloud tier requires a FlyDocs API key (`fdk_…`). Get one by signing in:

- `flydocs login` — opens your browser, signs you in, and stores a key for
  this machine at `~/.flydocs/credentials` (no file extension). Only the
  FlyDocs key is stored; the sign-in token is discarded.
- `flydocs login --device` — sign in with a code: the CLI prints a link and a
  code, you approve on any device (a phone works), and the CLI finishes on its
  own. Chosen automatically over SSH or on Linux with no display; the CLI says
  so when it does. `--no-device` forces the local browser flow instead.
- `flydocs login --project` — store the key for this project only, at
  `.flydocs/credentials.json`.
- `flydocs login --with-key <fdk_…>` — store a key you already have (headless
  machines, CI, SSH sessions). The old `auth` command still works as an alias.
- `flydocs init` — runs the browser sign-in itself when no key resolves, then
  picks the organization and workspace. `--key <fdk_…>` skips the sign-in.

Login never replaces a different key already stored globally without asking
(`--force` replaces it without asking).

Check and remove:

- `flydocs whoami` — the signed-in email, organizations, where the key comes
  from, the device name, and this repo's workspace.
- `flydocs logout` — revokes the key on the server, then deletes it locally
  (project file first if there is one, else global; `--project` / `--global`
  force the scope), and rewrites the FlyDocs OTel block in this repo's and your
  user-global `.claude/settings.json` so the revoked key is not left there.

Resolution order (first match wins):

1. `--key <fdk_…>` flag (`flydocs init`)
2. `FLYDOCS_API_KEY` environment variable (CI/CD) — always wins over files
3. `.flydocs/credentials.json` in the project (or the multi-repo workspace
   root)
4. `~/.flydocs/credentials` (global)
5. `FLYDOCS_API_KEY` in `.env.local` / `.env` (legacy — `logout` won't edit
   these; `flydocs clean --v1` migrates them)

If an operation fails with "API key not found", run `flydocs login`. Never
commit credentials to git.

## Remote MCP server

`flydocs connect remote` registers the hosted FlyDocs MCP server
(`https://mcp.flydocs.ai/mcp`, sign-in through your browser) with your coding
agents under the name `flydocs-cloud`. It never touches the local `flydocs`
server or the managed permission rules.

- `flydocs connect remote [--client claude|cursor|codex|vscode|all] [--yes] [--json]`
  — shows the exact change per agent, asks once, then writes. `--yes`, `--json`
  and a non-interactive shell never prompt. Re-running when the entry already
  matches changes nothing.
- `flydocs disconnect remote [--client ...]` — removes only the `flydocs-cloud`
  entry connect wrote.
- After connecting, start the agent and sign in (Claude Code: run `/mcp`). The
  first call opens the browser for consent.
- `flydocs doctor --tools` reports `mcp.remote.registration.<client>`.
- `FLYDOCS_MCP_INSTALL_CONFIG_URL` points connect at a development server's
  install-config.