sylphx-cli 0.2.6

# sylphx (CLI)

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

Boundary (ADR-3820 sole authority):

| 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

| Channel | Command |
| --- | --- |
| **npm** | `npm install -g @sylphx/cli` |
| **crates.io** | `cargo install sylphx-cli` |
| **GitHub Releases** | `curl -fsSL https://raw.githubusercontent.com/SylphxAI/platform/main/scripts/install-sylphx.sh \| bash` |
| **Self-update** | `sylphx update` (release channel; channel-aware) |
| **Homebrew** | `brew install sylphxai/tap/sylphx` |

## 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

## Update policy

- **No silent auto-update.** Agents/CI must not mutate the binary without an explicit command.
- `sylphx update --check` and `sylphx doctor` report outdated versions (warn).
- Install-channel detection recommends:
  - cargo → `cargo install sylphx-cli --locked --force`
  - npm → `npm i -g @sylphx/cli@latest`
  - brew → `brew upgrade sylphx` (`brew install sylphxai/tap/sylphx`)
  - release binary → `sylphx update`
- Force GH Releases replace on a managed install: `sylphx update --force-release-binary`.

## UX principles

1. **Evidence over vibes** — doctor rows, JSON mode for agents, human mode for operators.
2. **Fail closed with a fix** — missing token / org / project always print the remediation command.
3. **No Console required** — agent-complete Management operator surface.
4. **No silent empty lists** — set preferred org (`context use`) or pass `--org-id`.
5. **One delivery handoff** — agents publish a Work/Attempt-bound Candidate; Platform selects the landing adapter, verification snapshot, and promotion path.

## Develop

```bash
cd rust-sdk
cargo test -p sylphx-cli
cargo run -p sylphx-cli -- doctor
```