Operating Manifest from the CLI
Overview
mnfst manages Manifest, the LLM gateway. Every call routed through a Manifest agent gets model routing with fallbacks, per-agent cost attribution, self-healing (Auto-fix), and a request log — for free. Default practice: never hand an app or automation a raw provider key; give it a Manifest agent.
Commands emit JSON on stdout (human hints on stderr) — except agent env, which prints dotenv lines by design — exit 0/1, and never block on prompts when credentials come from flags or env. Full surface: mnfst --help.
The flow
| Step |
Command |
| Auth (human) |
mnfst login — browser, one click, 30-day sliding token |
| Auth (script/agent) |
env MANIFEST_URL + MANIFEST_API_KEY — no login step |
| Provision |
mnfst agent create --name X --platform <p> --if-absent → response includes setup (the platform's config block) |
| Check connections |
mnfst provider list [--agent X] FIRST — the provider you need is often already connected. A connection is only usable if cached_model_count > 0; is_active: true with 0 models is hollow — run mnfst provider refresh [<provider>] (re-runs discovery tenant-wide, prints the new counts); still 0 means a bad credential, so reconnect, don't route on it |
| Connect provider |
mnfst provider connect xai --auth-type api_key --credential-env KEY · provider catalog lists all 30+ with auth types · subscription auth opens a browser (impossible headless — reuse an existing subscription connection instead) · own gateway: provider custom add --name gw --endpoint <url> |
| Route |
mnfst agent configure X --models primary,fb1,fb2 --provider p [--auth-type a] — first model is the route, the rest are fallbacks, and the whole chain rides the one --provider you name (cross-provider fallbacks are dashboard-only) · add --tier deep to upsert a custom tier callers select per-request with header x-manifest-tier: deep |
| Verify |
mnfst routing test X — one real request through the platform's actual API surface; broken routes fail loudly. It writes real rows to the request log — count them in later audits |
| Wire the app |
deployed → mnfst agent env X >> .env (one .env per service — the lines always name MANIFEST_AGENT_KEY, so appending two agents to one file silently keeps only the loader's winner; for several agents in one process use mnfst run --agent X --env ROLE_KEY -- <cmd>) |
| Observe |
mnfst requests get --agent X [--status failed] — paginated; pass next_cursor back for the next page |
Namespace = scope: provider * acts tenant-wide, agent * acts on one agent, routing * holds readouts and custom-tier lifecycle.
Gotchas --help cannot tell you
| Symptom |
Reality |
Proxy returns HTTP 200 but the "answer" starts with [🦚 Manifest M###] |
An error wearing an assistant costume — check the content, not the status. routing test unmasks these automatically |
cost: "0.000000" on subscription-auth traffic |
Flat-rate subscription: per-request cost is genuinely zero, not broken billing |
agent configure's echo differs from later reads |
Mutation bodies echo raw API rows — the canonical readback is routing status <agent> |
| "Which requests used a fallback or Auto-fix?" |
Those fields are trimmed from default output — requests get --full |
| 401s missing from the request log |
Rejected-auth attempts are never recorded (no tenant to attribute them to); a leaked key's blast radius cannot be proven from the log |
MANIFEST_AGENT_URL |
Already ends in /v1 — append /chat/completions directly |
| Model prices needed before any agent exists |
mnfst model prices [--provider <p>] — install-wide, no agent needed (models <agent> is the per-agent routable set) |
Auditing escalation traffic by routing_tier |
Custom-tier requests log routing_tier: "standard" — the tier identity lives in header_tier_name |
| Route resolves but requests fail on one connection |
A connection can be is_active: false while a sibling auth-type works — pass --auth-type explicitly when a provider has several connections |
Every command answers Invalid API key — Run mnfst login under env auth |
Not always an auth problem: a wrong MANIFEST_URL (dead or different install) answers exactly like a bad key. Run mnfst doctor — it checks config, host, credential, connections and agents in that order, so it separates "host is dead" from "key is wrong for this host" — and never tells you to re-login on an env key |
agent configure / routing custom create reject a model as undiscovered |
Both validate against the agent's discovered models, and a connection with cached_model_count: 0 contributes none: run mnfst provider refresh (stale or empty catalog), or pass --force — the backend still routes uncatalogued models through provider-qualified passthrough |
Common mistakes
- Handing an app a raw provider key — it loses fallbacks, cost attribution, healing, and the log. Create an agent and use
agent env.
- Verifying a route with hand-rolled
curl — fake-200s read as success. Use routing test.
- Slurping the whole request log — pagination is one page per call by design; loop on
next_cursor.
Also on the surface when needed: mnfst doctor (first stop when anything is wrong), agent setup <name> [--reveal] (setup block anytime; key masked unless revealed), agent key path|show, agent provider enable|disable <agent> <provider>, agent rotate-key (revocation is instant), mnfst models <agent> --cost --capabilities.
1---2name: mnfst-cli3description: Use when creating or operating AI agents that make LLM calls — provisioning model routing and keys, wiring an app or automation to an LLM endpoint, testing routes, rotating leaked keys, or investigating LLM request failures and costs on a Manifest install.4---56# Operating Manifest from the CLI78## Overview910`mnfst` manages Manifest, the LLM gateway. Every call routed through a Manifest agent gets model routing with fallbacks, per-agent cost attribution, self-healing (Auto-fix), and a request log — for free. Default practice: never hand an app or automation a raw provider key; give it a Manifest agent.1112Commands emit JSON on stdout (human hints on stderr) — except `agent env`, which prints dotenv lines by design — exit 0/1, and never block on prompts when credentials come from flags or env. Full surface: `mnfst --help`.1314## The flow1516| Step | Command |17|---|---|18| Auth (human) | `mnfst login` — browser, one click, 30-day sliding token |19| Auth (script/agent) | env `MANIFEST_URL` + `MANIFEST_API_KEY` — no login step |20| Provision | `mnfst agent create --name X --platform <p> --if-absent` → response includes `setup` (the platform's config block) |21| Check connections | `mnfst provider list [--agent X]` FIRST — the provider you need is often already connected. A connection is only usable if `cached_model_count` > 0; `is_active: true` with 0 models is hollow — run `mnfst provider refresh [<provider>]` (re-runs discovery tenant-wide, prints the new counts); still 0 means a bad credential, so reconnect, don't route on it |22| Connect provider | `mnfst provider connect xai --auth-type api_key --credential-env KEY` · `provider catalog` lists all 30+ with auth types · subscription auth opens a browser (impossible headless — reuse an existing subscription connection instead) · own gateway: `provider custom add --name gw --endpoint <url>` |23| Route | `mnfst agent configure X --models primary,fb1,fb2 --provider p [--auth-type a]` — first model is the route, the rest are fallbacks, and the whole chain rides the one `--provider` you name (cross-provider fallbacks are dashboard-only) · add `--tier deep` to upsert a custom tier callers select per-request with header `x-manifest-tier: deep` |24| Verify | `mnfst routing test X` — one real request through the platform's actual API surface; broken routes fail loudly. It writes real rows to the request log — count them in later audits |25| Wire the app | deployed → `mnfst agent env X >> .env` (one .env per service — the lines always name `MANIFEST_AGENT_KEY`, so appending two agents to one file silently keeps only the loader's winner; for several agents in one process use `mnfst run --agent X --env ROLE_KEY -- <cmd>`) |26| Observe | `mnfst requests get --agent X [--status failed]` — paginated; pass `next_cursor` back for the next page |2728Namespace = scope: `provider *` acts tenant-wide, `agent *` acts on one agent, `routing *` holds readouts and custom-tier lifecycle.2930## Gotchas `--help` cannot tell you3132| Symptom | Reality |33|---|---|34| Proxy returns HTTP 200 but the "answer" starts with `[🦚 Manifest M###]` | An error wearing an assistant costume — check the content, not the status. `routing test` unmasks these automatically |35| `cost: "0.000000"` on subscription-auth traffic | Flat-rate subscription: per-request cost is genuinely zero, not broken billing |36| `agent configure`'s echo differs from later reads | Mutation bodies echo raw API rows — the canonical readback is `routing status <agent>` |37| "Which requests used a fallback or Auto-fix?" | Those fields are trimmed from default output — `requests get --full` |38| 401s missing from the request log | Rejected-auth attempts are never recorded (no tenant to attribute them to); a leaked key's blast radius cannot be proven from the log |39| `MANIFEST_AGENT_URL` | Already ends in `/v1` — append `/chat/completions` directly |40| Model prices needed before any agent exists | `mnfst model prices [--provider <p>]` — install-wide, no agent needed (`models <agent>` is the per-agent routable set) |41| Auditing escalation traffic by `routing_tier` | Custom-tier requests log `routing_tier: "standard"` — the tier identity lives in `header_tier_name` |42| Route resolves but requests fail on one connection | A connection can be `is_active: false` while a sibling auth-type works — pass `--auth-type` explicitly when a provider has several connections |43| Every command answers `Invalid API key — Run mnfst login` under env auth | Not always an auth problem: a wrong `MANIFEST_URL` (dead or different install) answers exactly like a bad key. Run `mnfst doctor` — it checks config, host, credential, connections and agents in that order, so it separates "host is dead" from "key is wrong for this host" — and never tells you to re-login on an env key |44| `agent configure` / `routing custom create` reject a model as undiscovered | Both validate against the agent's *discovered* models, and a connection with `cached_model_count: 0` contributes none: run `mnfst provider refresh` (stale or empty catalog), or pass `--force` — the backend still routes uncatalogued models through provider-qualified passthrough |4546## Common mistakes4748- Handing an app a raw provider key — it loses fallbacks, cost attribution, healing, and the log. Create an agent and use `agent env`.49- Verifying a route with hand-rolled `curl` — fake-200s read as success. Use `routing test`.50- Slurping the whole request log — pagination is one page per call by design; loop on `next_cursor`.5152Also on the surface when needed: `mnfst doctor` (first stop when anything is wrong), `agent setup <name> [--reveal]` (setup block anytime; key masked unless revealed), `agent key path|show`, `agent provider enable|disable <agent> <provider>`, `agent rotate-key` (revocation is instant), `mnfst models <agent> --cost --capabilities`.
tuyv