Agent index (llms.txt) — fetch this first, then the page it names.

CLI overview

orama is the human interface to an Orama network. One binary, three audiences: operators (orama status, upgrade, edit, remove, ssh, network), tenants (orama deploy, app, function, db, namespace) and maintainers, whose commands (build, push, rollout, inspect, invite, the node installer and the rest) live under orama maint, out of orama --help, and all work. The operator groups orama node, global, cluster, chain, monitor and nodes work too and are hidden from --help: orama upgrade, edit and remove replace their upgrade, edit and removal paths, and orama setup replaces the installer. Programs use the SDK and the gateway HTTP API instead. There is no dashboard and no Orama MCP server.

The pages under "CLI commands" in the sidebar are generated from the command tree, so every command and flag in them exists in the binary. This page covers what applies to all of them.

Install

brew install DeBrosDAO/tap/orama
orama version

Debian and Ubuntu packages and tarballs for macOS and Linux (amd64 and arm64) are on the releases page:

sudo dpkg -i orama_<version>_linux_amd64.deb

From source, in a checkout of the repository:

make build
./core/bin/orama version

Homebrew tracks the latest stable release, which can lag nightly pre-releases by several versions. orama node upgrade expects the CLI and the nodes to be on the same version.

First run: no cluster is configured

A fresh CLI knows no cluster. Add the one you use:

orama network add mycluster https://cluster.example.com
orama network use mycluster
orama auth login

The gateway URL must be https:// with a host (http:// only for a gateway on this machine). Every command sends its credential there. orama network add also takes --ca-file to trust a private or staging CA for that cluster only, and --network to record which network of the registry it runs on. orama network list and orama network current show what is configured, next to the networks built into the CLI. A network that publishes a manifest is added by its URL: orama network add https://example.org/networks/mine/manifest.json shows the chain id and the digest of the release root it would trust and asks you to type yes (--yes in a script). orama env is the old name of orama network: hidden, prints a deprecation line, and goes in the next release. The list is stored in ~/.orama/environments.json, and orama setup (or orama node setup --genesis) adds the cluster it creates, with its nodes and, for orama setup, the operator account orama status shows.

Which cluster, which namespace, which credential

• +--env <name> on a command picks an environment for that command; otherwise the active one is used.
• +orama auth login signs in to the active environment's gateway. orama auth login --namespace myapp signs in to a namespace. Credentials are stored per environment and namespace.
• +ORAMA_TOKEN supplies a credential for scripts and CI: either an API key (exchanged for a short-lived token) or a token. ORAMA_API_URL points a command at another gateway, for example a namespace's own host (https://ns-<name>.<domain>) for the four commands that run on the namespace gateway: namespace backup, restore, restore-key and rqlite export or import.
• +ORAMA_TOKEN_FILE is what a deployed app reads: a file with a token that the platform renews. See Deployments.

Global flags

--json works on every command. A command that prints a table emits one JSON object per row, keyed by the column headers lowercased with spaces as underscores (NODE ID becomes node_id). Commands that forward a gateway reply print it verbatim, so a field the CLI does not render is still there for whatever parses it. Status lines and progress are suppressed under --json, so the output is one document.

Colour and emoji

Colour and emoji appear only on a terminal. Piping gives plain ASCII markers (OK, WARN, ERROR). NO_COLOR set to anything, including empty, turns styling off even on a terminal.

Exit codes

RootWallet

Commands that reach a node or sign something (setup, node setup, maint push, maint rollout, maint build, ssh, monitor, auth login, anything that signs a chain transaction) ask the RootWallet desktop app's agent. See The agent. A command that seems to hang is usually an approval prompt in the app.

Command families