# CLI reference

Every command and flag of rungent, the command in rungent. Where it finds the host and token, the authoring commands, rungent serve, the files it keeps and its exit codes.

`rungent` is the command line of every rungent host, the tool that checks a catalog and generates a
host's documents, keys and branded CLI, and the server for hosts in other languages. It needs
Node 22 or later (24 for `serve`).

```bash
npm install -g rungent
rungent login https://console.example.com      # paste a token
rungent vm stop gpu-train-01                   # a command the host offers
```

```text
Usage: rungent [--host <url>] [--yes] <command> [args]
```

Output is JSON on stdout: indented on a terminal, one line otherwise. Messages and prompts go to
stderr. What the CLI is for is on [Surfaces](surfaces.md#a-cli-with-your-name).

## Global flags

They come before the command.

| Flag | Meaning |
|---|---|
| `--host <url>` | The host. An `http` or `https` URL; a trailing slash is dropped. |
| `--yes`, `-y` | Confirm writes without asking. |
| `--help`, `-h` | Print the usage; after a command, that command's help. |

## Host and token

| Variable | Meaning |
|---|---|
| `RUNGENT_HOST` | The host, when there is no `--host`. |
| `RUNGENT_TOKEN` | The token. When `RUNGENT_HOST` is set, it goes to that host only. It is never saved or printed. |

The host is `--host`, else `RUNGENT_HOST`, else the host `rungent login` last saved for this program,
else a branded CLI's preset host. The token is `RUNGENT_TOKEN`, else the one `login` saved for that
host. A branded CLI reads `<NAME>_HOST` and `<NAME>_TOKEN` by default (see [`brand`](#brand)).
In CI, set the variables and skip `login`; nothing is written to disk.

## Host commands

Host commands connect to `<host>/mcp` with `Authorization: Bearer <token>`. The built-ins are
`login`, `logout`, `status`, `tools` and `search`. When the host offers a command whose first word
is one of them, the host's command wins; `rungent:<name>` always runs the built-in
(`rungent rungent:login`).

| Command | What it does |
|---|---|
| `login [host-url] [--token-stdin]` | Asks for a token without echoing it (or reads stdin), checks it by listing the tools, saves it for the host and makes the host this program's default. Never reads `RUNGENT_TOKEN`. |
| `logout [host-url]` | Forgets the host's token and its cached tool list. |
| `status` | The host, the credential used (`login` or the variable's name), the MCP server's name and version, and the tool count. |
| `tools [--json]` | Every command the host offers you, with its usage and summary. |
| `search <query>` | Searches the product: the host's search over its search operations and docs. |

### Commands from the host

```bash
rungent <command words> [positional args] [--flags]
rungent <command words> --help
```

`rungent` lists the host's MCP tools and spells each as the words in its `_meta.rungent`, which come
from [`x-rungent.cli`](x-rungent.md#every-key). A tool without them becomes one command, its name with
`_` as `-`. When several commands match, the longest wins.

| Input | How to write it |
|---|---|
| Positional arguments | The tool's `args`, in order. |
| Other inputs | `--page-size 20` or `--page-size=20`; `_` in a name becomes `-`. |
| Booleans | `--forced`, `--no-forced`, `--forced=true`. |
| Arrays | Repeat the flag: `--tag a --tag b`. |
| Objects | A JSON object: `--labels '{"team":"ml"}'`. |
| The whole input | `--input-json <file\|->`: a JSON object from a file or stdin. Flags override its keys. |
| End of flags | `--`: everything after it is positional. |

A missing required input fails with exit code 2 before anything is sent. A write asks for
confirmation on the terminal; `--yes` accepts it, and without a terminal it is declined unless
`--yes` is given. The result is the tool's structured content, else its text parsed as JSON; a
tool error goes to stderr as `error: …`, with exit code 1.

## Authoring commands

They work on an OpenAPI document and never contact a host. `--openapi` takes a JSON file or an
`http(s)` URL; `-o` (`--out`) writes to a file instead of stdout.

### `check`

```bash
rungent check --openapi <file|url> [--routes routes.txt]
```

Prints every catalog issue as `<where>: <message>` and exits 1 when there is any; otherwise prints
`ok: N operations` on stderr. The rules are in [x-rungent](x-rungent.md#validation-rules). `--routes`
lists the requests your UI makes, `METHOD /path` per line, and fails each one no operation serves;
mark a route only the browser needs with `# browser-only: <reason>`.

### `skill`, `llms`, `reference`, `docs`

```bash
rungent skill --openapi <file|url> --product <name> --url <url> [--guide guide.md] [--cli-command acme] [-o SKILL.md]
rungent llms --openapi <file|url> --product <name> --url <url> --summary <text> [-o llms.txt]
rungent reference --openapi <file|url> [-o reference.md]
rungent docs --openapi <file|url> --product <name> --url <url> --summary <text> [--guide f] [--cli-command c] -o <dir>
```

`skill` writes the agent skill rungent serves at `/skill.md`: frontmatter, your guide, how to connect,
the safety rules and the operation index. `llms` writes `llms.txt`; `reference` a Markdown
reference of every operation; `docs` all three into a directory.

### `keys generate`

```bash
rungent keys generate --kid rungent-2026-11 [-o rungent-2026-11.private.jwk]
```

Prints the public JWK, which your API pins, on stdout, and writes the private JWK, rungent's signing
key, to a new file with mode 0600 (default `<kid>.private.jwk`). It never overwrites a file and
never prints the private key. Both are portable Ed25519 JWKs that Node, Bun, Deno and workerd
import alike.

### `brand`

```bash
rungent brand --name acme [--host https://console.example.com] [--env-host VAR] [--env-token VAR] -o acme-cli [--npm-name @acme/cli]
```

Writes an npm package (`package.json`, `bin/acme.js`, `README.md`) whose bin `acme` runs this CLI
under that name.

| Flag | Meaning |
|---|---|
| `--name` | Required: the command, lowercase letters, digits and `-`. |
| `-o`, `--out` | Required: the package's directory. |
| `--host <url>` | A preset host. Leave it out for a product customers host themselves. |
| `--env-host`, `--env-token` | The variables it reads. Default `<NAME>_HOST` and `<NAME>_TOKEN`, the name uppercased with `-` as `_`. |
| `--npm-name` | The package name. Default `<name>-cli`. |

To build the CLI into a program of your own, call `run(argv, {program?, host?, env?})` from
`rungent/cli`; it answers the exit code. This is what `brand` writes.

## `serve`

```bash
rungent serve
```

Runs rungent as an HTTP server beside a host, configured from `RUNGENT_*` environment variables, until
`SIGTERM` or `SIGINT`. A missing or invalid variable exits 2 with its name. Every variable is in
[Deploy](deploy.md#configure-it).

## Files

| Path | Content |
|---|---|
| `~/.config/rungent/hosts.json` | The tokens `login` saved, by host, and each program's default host. Mode 0600 in a 0700 directory. |
| `~/.cache/rungent/tools/<hash>.json` | The tool list, cached for five minutes per host and token. |

`XDG_CONFIG_HOME` and `XDG_CACHE_HOME` move these directories. A branded CLI shares them, with its
own default host.

## Exit codes

| Code | Meaning |
|---|---|
| `0` | OK. |
| `1` | A tool error, a JSON-RPC error, or `check` found issues. |
| `2` | Usage: an unknown command or flag, a missing or invalid value. |
| `3` | Auth: no host, not logged in, or the host answered 401 or 403. |
| `4` | Network: the host cannot be reached, or answered another HTTP error. |
