mantos

The command-line client for Mantos — reach your tenant's API from a terminal, a CI job, a container, or an agent session.

pipx install mantos     # or: pip install mantos

One environment variable

A Mantos API key carries its own tenant slug, so the key is the whole configuration:

export MANTOS_API_KEY=mtk_<tenant>_<keyid>_<secret>

mantos env list
mantos agent list --env dev

There is nothing else to set — no host, no tenant, no profile. Mint a key in the Mantos console (Settings → API keys); the secret is shown once, at mint, and is not recoverable afterwards.

Most commands read one environment. Export MANTOS_ENV to stop typing --env; the flag still wins where you pass it.

Commands

Objects are singular, and the verb comes last — mantos <object> <verb>.

mantos env      list | get SLUG
mantos agent    list | get AGENT_ID           --env
mantos skill    list | get SKILL_ID           --env
mantos history  list | get RECORD_ID          --env
mantos audit    list
mantos knowledge base      list | get BASE_ID
mantos knowledge reference list | get REFERENCE_ID

mantos auth status
mantos config  show | set-host HOST
mantos api     METHOD PATH [--field K=V] [--raw-field K=V]

Every command takes --json and --timeout S. Run mantos <object> --help for the filters a list accepts — --status, --since, --limit and so on, which differ by object because they are exactly what the API accepts there.

Lists print a table for a person; --json prints the response body unaltered, on one line, for a parser. Nothing the table renderer does can reach that output.

mantos auth status asks the server who your key is — its tenant, the person whose authority it carries, when it expires, and what it was granted. Unlike config show, which reads your shell, it catches a key that is revoked, expired, or whose owner was deactivated.

The escape hatch

The curated commands cover reading. mantos api reaches any tenant API path directly, including everything that writes:

mantos api GET  api/tenant/v1/skills
mantos api POST api/tenant/v1/knowledge/bases --field name=Support \
           --field root_topic=Onboarding

PATH includes any query string, and a leading slash is optional — on Git Bash, omitting it avoids the shell rewriting the argument into a Windows filesystem path before the CLI sees it.

--field K=V builds a JSON body, parsing V as JSON when it parses and sending it as a string when it does not; --raw-field always sends a string. Neither is accepted on GET or HEAD, where the API takes no body — silently dropping a field would let you believe a filter was applied that never was.

Output, so a parser and a person can both read it

The answer is the only thing written to stdout — the response body, or the table a list renders. The status line for a failure goes to stderr, and so does anything that is commentary rather than data: No results., and the hint naming the --cursor to pass for the next page. Pipe stdout straight into jq without stripping anything, and still see why a call went red.

Exit codes

A 403 is 1, not 3. Authenticated-but-refused is a different fact from credential-rejected: a key whose grants are narrower than its owner's authority is supposed to be refused inside a scope it only partly holds, and that is the authorization gate working rather than a broken key.

Host resolution

MANTOS_HOST › the tenant named by the key › a host stored with mantos config set-host.

The environment variable wins so a support session, a smoke test, or a one-off against another deployment needs no stored state and leaves none behind. A stored host is the last resort precisely because it is invisible: a pin left behind by an earlier session must not silently outrank the credential in front of it.

Mantos is a product of Systematic Labs LLC. This client talks to a deployed Mantos tenant over HTTPS and contains no server code.