Metadata-Version: 2.5
Name: mantos
Version: 0.2.0
Summary: The Mantos CLI — reach your Mantos tenant's API from a terminal
Project-URL: Homepage, https://mantos.cloud
Author: Systematic Labs LLC
License-Expression: LicenseRef-Proprietary
Keywords: agents,api,cli,mantos
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click>=8.2
Requires-Dist: httpx>=0.25
Description-Content-Type: text/markdown

# mantos

The command-line client for [Mantos](https://mantos.cloud) — reach your tenant's
API from a terminal, a CI job, a container, or an agent session.

```bash
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:

```bash
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:

```bash
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

| Code | Meaning |
|------|---------|
| `0` | The request succeeded (2xx). |
| `1` | The request was made and did not succeed — any non-2xx other than 401, plus a transport failure. |
| `2` | The invocation was wrong, or `MANTOS_API_KEY` is not set. Nothing was sent. |
| `3` | The credential was not accepted (401). |

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.
