sylphx-cli 0.2.10

# sylphx (CLI)

Production **Rust** operator CLI for the Sylphx Platform **Management plane**.

**Customer install/update contract (SSOT):**  
[`docs/how-to/install-and-update-sylphx-cli.md`](../../docs/how-to/install-and-update-sylphx-cli.md)  
**Policy:** [ADR-4437](../../docs/adr/ADR-4437-cli-distribution-and-update-authority.md)  
**Site:** [sylphx.com/docs/cli](https://sylphx.com/docs/cli)

## Boundary (ADR-3820)

| In scope | Out of scope |
| --- | --- |
| Orgs, projects, deploy, env, logs, resources, domains, secrets, tokens, billing | Customer app BaaS runtime (`sk_*` / tenant APIs) |
| Agent/CI automation via `SYLPHX_TOKEN` | Console-only visual builders |
| Device-flow human login | Direct cluster / DB mutation |

Dogfoods `sylphx-sdk-management` (Protobuf wire `sylphx.platform.v1`).

## Install

Pick **one** channel and use the **same** channel to upgrade later.

| Channel | Command |
| --- | --- |
| **curl (standalone)** | `curl -fsSL https://raw.githubusercontent.com/SylphxAI/platform/main/scripts/install-sylphx.sh \| bash` |
| **npm** | `npm install -g @sylphx/cli` |
| **Cargo** | `cargo install sylphx-cli --locked` |
| **Homebrew** | `brew install sylphxai/tap/sylphx` |

There is **no** WASM operator CLI. npm only distributes the Rust binary.

## Update

**Update the way you installed.** Silent auto-update is forbidden.

| Install channel | Upgrade |
| --- | --- |
| curl / standalone | `sylphx update` or re-run the install script |
| npm / pnpm / bun | `npm install -g @sylphx/cli@latest` (or pnpm/bun) |
| Cargo | `cargo install sylphx-cli --locked --force` |
| Homebrew | `brew upgrade sylphx` |

```bash
sylphx update --check   # status only
sylphx update           # explicit upgrade
```

Happy path is short (e.g. `sylphx 0.2.6 is current`). Details: `--check` / `--json`.

## Day-1

```bash
sylphx login                 # browser device approval (user JWT)
sylphx doctor                # auth + API base + context diagnostics
sylphx whoami
sylphx context use --org-id org_… --slug my-org
sylphx projects list
sylphx link --project proj_… --org-id org_…
sylphx candidates publish --work-item wi_… --producer-attempt att_…
sylphx deploy proj_… --env production
sylphx status proj_…
sylphx logs --project proj_… --tail 100
```

Agent / CI:

```bash
export SYLPHX_TOKEN=svc_...
export SYLPHX_API_URL=https://api.sylphx.com/v1   # optional; host-only is auto-healed to /v1
sylphx doctor --json
sylphx projects list --org-id org_… --json
```

## Auth model

| Credential | How | whoami | deploy/projects |
| --- | --- | --- | --- |
| OAuth session (device login) | `sylphx login` | ✅ user + orgs | ✅ (needs org context) |
| Service token `svc_*` | `SYLPHX_TOKEN` / `login --token` | no user profile (expected) | ✅ |

Device login discovers the RFC 8414 authorization server, stores a rotating
access/refresh pair atomically, and refreshes before expiry. `sylphx logout`
revokes both credentials before clearing the local file; `--local-only` is an
explicit offline containment option.

Credentials live at `~/.config/sylphx/credentials.json` (mode 0600 in a mode
0700 directory). Access, refresh, and device credentials are never printed.
Preferred org: `~/.config/sylphx/context.json`.
Directory link: `./.sylphx/project.json` (`sylphx link`).

API base URLs are **always normalized** to include `/v1`. A poisoned
`https://api.sylphx.com` credential is healed on read so `/whoami` never
hits the bare-root 404 again.

## Command surface

See `sylphx version-info --json` → `shippedCommands` for the authoritative list.

Highlights beyond the core deploy loop:

- `doctor` / `config` / `context` / `link` / `unlink` / `open` / `update` / `wait` / `catalog` / `init` / `inspect` / `tail`
- `candidates publish` / `candidates get` for the immutable, Work-bound delivery handoff
- `domains` / `secrets` / `tokens` / `billing` / `services` / `webhooks` / `certs` / `releases` / `runners` / `sandbox` / `volumes` / `users`
- `admin get` / `delivery get` passthrough for residual Management routes
- `api METHOD PATH` escape hatch for any Management REST route