Command line interface

Drive the Realm API from your terminal with the Realm CLI

Overview

The Realm CLI wraps the same REST API documented in this section. It gives you agent chats with live streaming answers, document management for API data sources, and an interactive chat session, all from a terminal. Every command accepts --json, so the CLI also works as a scripting tool in pipelines.

Installation

The CLI ships as a single standalone executable. On macOS and Linux:

curl -fsSL https://storage.googleapis.com/realm-cli/install.sh | bash

On Windows, in PowerShell:

irm https://storage.googleapis.com/realm-cli/install.ps1 | iex

The installer downloads the executable for your platform together with SHASUMS256.txt, verifies the SHA-256 checksum before installing, installs to $HOME/.realm/bin/realm (%USERPROFILE%\.realm\bin\realm.exe on Windows), adds that directory to your PATH, and runs realm --version to confirm the result. Nothing else is required: the executable carries its own runtime.

Prebuilt executables cover macOS x64 and arm64, Linux x64 and arm64 for both glibc and musl, and Windows x64 and arm64. Three environment variables change what the installer does: REALM_INSTALL_DIR selects the install directory, REALM_VERSION pins an exact version such as 0.2.0, and REALM_RELEASE_URL points at an alternate release location, which realm update honours as well.

The CLI is also published to npm, which requires Node.js 22.12 or newer:

npm install -g @realmtechnologies/cli
realm --version

Upgrading

An executable installed with the install script updates itself:

realm update
realm update --check

realm update downloads the latest release for the running platform, verifies its checksum, and replaces the running executable in place. realm update --check reports the latest release without installing it, and realm update --json prints {current, latest, channel, target, update_available, updated}.

When a newer release exists, an interactive run prints one notice on standard error, such as Update available: 0.1.1 → 0.2.0. Run realm update.. The version lookup runs in a detached background process at most once every 24 hours and is cached in the CLI configuration directory, so it never delays or fails a command. The notice is suppressed with --json, when standard error is not a terminal, when CI is set to anything other than false, and when REALM_CLI_NO_UPDATE_CHECK=1.

On an npm installation, realm update declines and points you at npm install -g @realmtechnologies/cli@latest.

Run realm --version to see which version is installed. An executable also reports its release target, for example 0.1.1 (linux-x64).

Authentication

Create an API key first. See API keys for how to create and manage keys, and note that a key carries scopes: chat:read, chat:write, and documents:write.

Interactive login

realm auth login

The command prompts for your key, verifies it against GET /agents, and stores it in your operating system credential store. When no credential store is available, for example on a headless Linux host, the key is written to a configuration file with owner-only permissions instead.

The standalone executables always use that configuration file, because the credential-store binding is a per-platform native library that cannot be embedded in a cross-compiled executable. The npm installation uses the credential store whenever one is available. Everything else about the two installations is identical.

A key that carries only documents:write cannot list agents. Login still accepts and stores such a key, and notes that chat commands are unavailable with it. A key that fails authentication outright is never stored.

Check or remove the stored key:

realm auth status
realm auth logout

Continuous integration

Set REALM_API_TOKEN in the environment. It takes precedence over any stored key, so no login step is needed in a pipeline.

export REALM_API_TOKEN="realm_api_..."
realm agents list --json

Multiple tenants

The default base URL is https://app.withrealm.com. Single-tenant deployments live on their own host, which you select with --base-url on any command, or persist with realm config set base-url. The REALM_BASE_URL environment variable overrides the persisted value.

Keys are stored per host, because API keys are tenant scoped. Logging in against two hosts keeps two keys side by side, and each command uses the key of the host it targets. Storing a key for a host also clears any copy of it held by the other store, so a single key per host is all the CLI can ever resolve.

The base URL must use https://, because the key travels in an Authorization header. Plain http:// is accepted only for local development hosts: localhost, *.localhost, 127.0.0.1, and ::1.

realm config set base-url https://acme.withrealm.com
realm auth login
realm agents list --base-url https://app.withrealm.com

Global flags

Flag	Description
--json	Print the raw API payload with no decoration.
--base-url <url>	Target host for this invocation.
--token <token>	Use this key instead of the stored or environment key.

Command reference

Authentication and configuration

Command	Description
realm auth login	Prompt for an API key, verify it, and store it for the active host.
realm auth status	Show the active host, where its key came from, and a masked key prefix.
realm auth logout	Remove the stored key for the active host.
realm config get base-url	Print the configured base URL.
realm config set base-url <url>	Persist the base URL used by later commands.
realm update	Replace the running executable with the latest release. Accepts --check.

Agents and data sources

Command	Description
realm agents list	List the agents your key can reach, including which one is the default.
realm connectors list	List the API data sources of your organization. Their IDs are the data source IDs used by the document commands.

Chat

realm chat

Running realm chat without a subcommand opens an interactive session: pick an agent, send messages, and watch answers stream in. Tool calls that need approval are presented as a prompt, and answering continues the same chat. The session prints its chat ID on exit so you can resume the transcript with realm chat messages. The session needs a terminal on both input and output, so with --json, redirected output, or piped input the command points you at realm chat ask instead.

Command	Description
realm chat ask "<message>"	Send one message and print the answer.
realm chat list	List chats. Accepts --limit, --after, and --order.
realm chat messages <chat_id>	Print the messages of a chat in full, one block per message headed by its ID and role. Accepts --citation-style.
realm chat delete <chat_id>	Delete a chat.
realm chat approve <chat_id>	Resume a chat that is waiting for tool approval.

Flags for realm chat ask:

Flag	Description
--agent <id>	Agent to ask. Required.
--chat <id>	Continue an existing chat instead of starting a new one.
--stream	Print the answer token by token as it is generated.
--research	Run the request in research mode.
--tool-mode <mode>	One of ask, act, or off.
--citation-style <style>	One of link or remove.
--output-format <format>	One of markdown or text.
--answer-only	Return only the final answer text. Non-streaming only.
--eco	Use cost-efficient models when the agent allows it.
--tool-connector <id>	Replace the configured external tools for this request. Repeatable.
--var <key=value>	Set a prompt variable. Repeatable.

realm chat ask --stream --agent ag_123 "Summarize our vacation policy"

When an answer stops on a tool approval, the CLI prints the pending tool calls together with the exact realm chat approve invocation that resumes the chat.

Documents

Every document command takes a data source ID from realm connectors list and requires the documents:write scope.

Command	Description
realm documents upsert <data_source_id> --file <path>	Create or update documents from a JSON file, in batches of 100.
realm documents list <data_source_id>	List documents. Accepts --fields, --cursor, --limit, and --all. With --fields the table shows exactly those columns in the order given; otherwise it shows the fields the API returned. Object values such as meta print as compact JSON.
realm documents get <data_source_id> <document_id>	Print one document.
realm documents delete <data_source_id> <document_id>	Delete one document.
realm documents prune <data_source_id> --older-than <timestamp>	Delete documents not updated since an ISO 8601 timestamp. Asks for confirmation, which only --yes skips. The prompt needs an interactive terminal on both input and output, so with --json, redirected output, or piped input the command refuses to run without --yes.
realm documents upload <data_source_id> <file>	Upload a file for indexing. The file is streamed, so large files do not have to fit in memory.

realm documents upsert int_123 --file ./docs.json

The upsert file holds either { "documents": [...] } or a bare array of documents, with the fields described in the upsert documents endpoint.

Flags for realm documents upload:

Flag	Description
--title <title>	Document title. Defaults to the file name.
--id <id>	Document ID to upsert. A new document is created when omitted.
--mime-type <type>	Content type of the file. Inferred from the file name when omitted.
--url <url>	Source URL recorded on the document.
--verified	Mark the document as verified.
--read-access <email>	Restrict the document to this user. Repeatable. Omit it to leave the document readable by everyone in Realm.
--meta <key=value>	Set a metadata field. Repeatable.
--created-at <timestamp>	Document creation time, as an ISO 8601 timestamp.
--updated-at <timestamp>	Document update time, as an ISO 8601 timestamp.

Scripting

With --json, a command prints machine-readable JSON on standard output and nothing else, which makes it safe to pipe into a parser such as jq.

realm agents list --json | jq '.data | length'

Most commands pass the API response through unchanged, so the endpoint reference describes their payload. These are the exceptions:

Command	JSON shape
realm auth login	{ "host", "source", "agents", "staleKeychain" }, where agents is the reachable agent count, or null when the key cannot list agents, and staleKeychain is true when a previous key is still in the OS keychain and would take precedence.
realm auth status	{ "host", "source", "token", "agents" }, with token masked.
realm auth logout	{ "host", "loggedOut" }.
realm documents list --all	{ "documents": [...] }, with every page combined and the per-page cursor fields dropped.
realm documents upload	{ "sourceId" }. The one-time upload URL is used internally and never printed.
realm documents upsert	{ "results" }, plus { "error" } describing the batch that stopped the run when one fails partway. error.outcome is failed when the API rejected the batch and unknown when no response arrived.
realm chat ask --stream	Newline-delimited JSON: one object per stream event, not a single payload.

Indexing is asynchronous, so treat a successful realm documents upsert as accepted rather than searchable. An upsert of more than 100 documents is sent in batches; if a batch fails, the command reports the results of the batches that already succeeded, so you can retry only the remainder instead of duplicating accepted documents. If a batch never returns a response, its outcome is reported as unknown: the server may have applied it, so replay it only when every document in it has an explicit id.

Without --json, redirected output is tab-separated. Cell values are escaped, so a tab, newline, carriage return, or backslash inside a field becomes \t, \n, \r, or \\, and every record stays on one line with a fixed column count.

A streamed answer is occasionally revised by the agent, for example when it repairs the language of a reply. On a terminal the CLI erases the answer and reprints it; with redirected output it cannot erase, so it prints a [answer revised] marker line before the replacement.

Exit codes

Code	Meaning
0	Success.
1	Usage error, such as a missing argument or an unreadable file.
2	Authentication error, from a 401 or 403 response.
3	API error, from any other failing response, a transport failure such as an unreachable host or a request that exceeded the 60-second response deadline, a partial failure such as an upsert where some documents were rejected, or a streamed answer that ended before the API reported completion.
70	Internal CLI failure. Reported with a stack trace; please open an issue.
130	Interrupted with Ctrl+C.

Rate limits

The CLI is bound by the API limit of 600 requests per minute per organization per endpoint. When you exceed it, the request fails with 429 Too Many Requests, and the CLI reports the Retry-After hint from the response. Space out scripted loops and back off when you hit the limit.