ragen command on your PATH. It scaffolds an installation, moves documents in and out of its knowledge base, and searches it — and it grows toward managing an installation end to end, signing in and checking its health included, without leaving your terminal.
The package is
ragen-cli; the command is ragen. npm declines the plain name because its similarity filter reads it as too close to existing packages, so the install line differs from what you type afterwards.Requirements
The CLI asks for Node.js 22 or newer (since 0.3.0; earlier versions accepted 20, which no longer gets security fixes). That is deliberately lower than the Node.js 24 a Ragen installation itself needs. This is a client — refusing to print help on an older runtime would be needlessly strict.ragen create still enforces the real requirement at the point where an older Node would damage the install.
What it does today
ragen create hands the work to create-ragen-app and forwards your arguments unchanged, so these two are equivalent:
Connect to an installation
Every command exceptcreate talks to an installation’s public API. Create an API key under Organization → API keys, then save it once:
ragen login asks for the key without echoing it, checks it against the installation, and saves the address and key only if the key is accepted. You can also pipe the key in, which suits a CI job:
--url and --api-key take precedence over both. The saved key is only ever sent to the address it was saved for: when --url or RAGEN_API_URL names a different host, pass a key for it explicitly, or the command stops rather than send the saved one there.
Check the connection
ragen doctor shows which address and key are in use and where each one came from, which is usually what is wrong when commands disagree. It tells “nothing answers at this address” — including the panel’s address given in place of the API’s — apart from “the key was refused”, and warns when a newer CLI is on npm. It exits with a non-zero code when a check fails.
ragen doctor checks this client’s path to an installation. Whether the installation itself is configured well — its environment, model routes and queue — is checked on the host, where the setup page and npm run gateway:preflight report it.Upload and manage documents
ragen kb works on the knowledge base’s files through /v1/files:
Every subcommand accepts
--json to print the API’s response instead of a table.
The API key decides where files go. A key scoped to the whole knowledge base uploads to and lists the files that belong to no assistant. A key scoped to an assistant works on that assistant’s files. The CLI has no option for this — it would only be able to disagree with the server.
upload takes files, not directories. Let your shell expand a pattern such as docs/*.pdf.
Use it in a script
Bothupload --wait and status exit with a non-zero code when a file fails to index. --wait also exits non-zero when a file is still indexing at the timeout, and prints the ragen kb status command to check it later.
Rate limited; waiting 60s before note-11.md. instead of the rest failing. A limit that does not lift within two minutes — such as a monthly usage limit — is different: the CLI prints the server’s message and stops the batch. While waiting for indexing it checks all files in a single request every few seconds, so a large batch does not use up the limit by itself. If checking fails partway, it stops waiting but still prints what was uploaded — with --json, the file ids — and exits with a non-zero code.
Search the knowledge base
ragen search calls /v1/search. It prints the same PII-redacted context block that the chat endpoint passes to its model, followed by the files it came from. When an answer in chat looks wrong, this shows whether retrieval found the right passage or the model ignored it.
Ask a question
ragen ask sends one message through /v1/chat — the same retrieval, guardrails and usage limits as chat in the panel — and prints the answer as it is written. When you redirect the output to a file or a pipe, it waits for the complete answer instead, so text a guardrail withdraws never lands there; pass --stream to stream anyway.
ragen ask exits with a non-zero code when the answer is cut off before the API finishes it, so a script does not mistake a truncated answer for a short one. If an output guardrail stops an answer partway, the CLI notes that the text already printed was withdrawn and then prints the refusal.
To find an assistant’s id, list the assistants your key can see:
A key scoped to the whole knowledge base can list every assistant but cannot answer as one. The API refuses with
The API key is not allowed to do this. Create a key scoped to that assistant instead.What is coming
These commands are listed inragen help under Not built yet:
ragen plugin is the furthest out, and it waits on something larger than the CLI. Ragen’s extension API is MCP — third-party code runs in its own process and never inside the application — and the piece that lets you point Ragen at a server of your own is designed but not yet built. Until then, see MCP connectors for the connectors that ship today.
Versioning
The CLI talks to an installation over the public API, and self-hosted deployments run many versions at once. Its version number describes the client, not the server you point it at. Upgrade it like any other global package:Next steps
Quick Start
Scaffold an installation and ask your first question of your own documents.
Roadmap
What is being built next, across the product and the tooling around it.
API Reference
The endpoints behind
ragen kb, ragen search and ragen brain.Request a Command
Tell us what you would automate first — that is what decides the order.