rungentReference
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).
npm install -g rungent
rungent login https://console.example.com # paste a token
rungent vm stop gpu-train-01 # a command the host offers
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.
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).
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#
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. 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#
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. --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#
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#
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#
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#
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.
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. |
For agents: cli-reference.mdEdit this page