@belvedir/cli

The Belvedir platform from your shell: projects, API keys, conversations, tasks, task groups, training runs, benchmarks, model routing, and balances.

npm install -g @belvedir/cli
belvedir login          # opens your browser (Google or GitHub sign-in)
belvedir projects
belvedir keys my-agent  # the project's API keys (minting stays in the dashboard)
belvedir train my-agent --method sft

Auth

belvedir login signs in as your real Belvedir account, so every command sees exactly what the dashboard shows you (organizations you belong to, projects you can access, your own API keys).

• Browser (default): opens the Belvedir dashboard, where you're usually already signed in; one click on Approve and the terminal is in.
• Password: belvedir login --email [email protected] for email/password accounts, no browser needed.

The session is stored in ~/.config/belvedir/credentials.json (owner-only permissions, re-applied on every write) and refreshes automatically. belvedir logout revokes that session on the server (only this session — your browser and other terminals stay signed in) and then deletes the file; if the platform can't be reached it still signs you out locally and the server session expires on its own.

Commands

Run belvedir help for the full list.

Reads: whoami, orgs, projects, keys <project>, conversations <project>, traces <project>, tasks <project>, groups <project>, cleaning <project>, models, runs <project>, benchmarks, benchmarks show <run-id>, benchmarks catalog, environments <project>, environments export <project> --id env-id (writes a Harbor dataset), harness <project>, repos <project>, signals <project>, validation <project>, routing <project> / routing stats / routing routers (auto + drafts), review <project>, setup <project>, members <org>, access <project>, balance, billing <org>, github.

Actions: projects create / rename / delete, keys revoke / rename (key MINTING is deliberately dashboard-only), train (--method sft|opsd|rl, and for RL --reward judge|similarity --algorithm auto|grpo|ppo) / train cancel, analyze, review approve|reject, setup <project> --target/--loops/--autonomy/--keys, autotrain, benchmarks create / add / run (with --attempts, --grading, and --model for evaluating a fine-tune) / cancel / delete, environments generate (--preset or --repo, or neither for the platform's default driver: Belvedir Runner on Harbor when the deployment hosts Harbor, else the in-sandbox Belvedir Runner; --synthesize adds gated rubric verifiers; the pass runs on the worker for 6 to 10 minutes and the CLI polls it, --no-wait returns at once) / status <environment-id> [--wait] / simulate / declare, simulations run, harness map, repos add / remove, models download, deploy <model-id> (Together, orchestrated start-to-endpoint), routing set / pin / unpin (these edit the auto router) / promote <router-id>, orgs create / rename / delete, members invite / remove / role, access set, outcome, billing buy / redeem / payg (browser flows: the CLI prints and opens the URL; payg --on|--off|--remove manages the saved card), github connect.

Projects are referenced by UUID or by name when it's unambiguous. Every read takes --json for raw output ready to pipe into jq. Destructive commands (projects delete, orgs delete) require a literal --yes. Training and benchmark runs launched from the CLI are not billed; only hosted inference charges the organization's balance, exactly as in the dashboard.

Using with coding agents

If an AI coding agent will run belvedir, sign in with belvedir login --readonly: the session is marked server-side and every write command (approving proposals, launching runs, changing members or routing) is rejected at the platform, even if something bypasses the CLI and calls the API directly — including pasting the token into a browser: the dashboard refuses every write (server action) from a read-only session too. belvedir logout is the one write a read-only session can make. Prefer a member account with project exclusions over the org owner's account for agent machines, and never approve a cli-auth link you didn't initiate: the approve page shows a verification code that must match the one your terminal printed.

Notes

• Requires Node 18+. No dependencies.
• Sending traces is not the CLI's job; that's the belvedir SDK.
• Self-hosted or staging platform: belvedir login --platform https://your-host. Login only accepts https URLs and refuses localhost: a session minted for a local server is still a real account session.