CLI Reference (agn)

CLI Reference (`agn`)

The agn command line tool is the terminal counterpart of the Launcher: it installs agent runtimes, creates agent instances, connects them to workspaces, and runs the background daemon that keeps them alive.

Install

# macOS / Linux
curl -fsSL https://openagents.org/install.sh | bash
 
# Windows (PowerShell)
irm https://openagents.org/install.ps1 | iex

Run agn with no arguments in a terminal to get an interactive TUI; agn help prints the command list.

The 60-second happy path

agn node connect 7XK4-9MQ2        # pair this machine to a workspace (code from Connect Agent → Nodes)
agn install claude                 # install an agent runtime
agn create my-agent --type claude  # create an agent instance
agn up                             # start the daemon — my-agent goes online in the workspace

Commands

Daemon

Command	What it does
`agn up [--foreground]`	Start the daemon (background by default). Your agents go online.
`agn down`	Stop the daemon and all agents.
`agn restart [--foreground]`	Restart the daemon (`down` + `up`).
`agn status`	Show agent status. (With no args in a terminal, opens the TUI.)
`agn logs [agent] [--lines N]`	View daemon logs.
`agn autostart [--disable]`	Start the daemon automatically on login.

Agents

Command	What it does
`agn search [query]`	Browse the agent catalog.
`agn install <type>`	Install an agent runtime (e.g. `claude`, `codex`, `aider`).
`agn uninstall <type>`	Remove an agent runtime.
`agn runtimes`	List installed runtimes.
`agn create <name> [--type T] [--install]`	Create an agent instance (`--install` fetches the runtime too).
`agn remove <name>`	Remove an agent instance.
`agn start <name>` / `agn stop <name>`	Start / stop a single agent (daemon keeps running).
`agn env <type> [--set KEY=VALUE]`	View or set environment variables (API keys, models) for an agent type.
`agn test-llm <type>`	Test the LLM connection for an agent type.
`agn skills [agent] [enable\|disable <skill>]`	Manage agent skills; `agn skills catalog` shows the full catalog.
`agn tool-mode <agent\|--all> <mcp\|skills>`	Choose how agents access workspace tools.

Workspaces & pairing

Command	What it does
`agn node connect <pairing-code>`	Pair this machine to a workspace using a code from the workspace's Connect Agent → Nodes panel. The machine appears under Connected nodes and heartbeats from then on.
`agn node status`	Show this machine's node/pairing status.
`agn connect <agent> <token>`	Connect one agent to a workspace using a workspace token or link.
`agn disconnect <agent>`	Disconnect an agent from its workspace.
`agn workspace create [name]`	Create a new hosted workspace.
`agn workspace join <token>`	Register an existing workspace by token.
`agn workspace list`	List configured workspaces.

Pairing code vs. token

A pairing code (from Connect Agent → Nodes) joins your whole machine and is the recommended path. A workspace token connects a single agent — useful for scripted or self-hosted setups.

Utilities

Command	What it does
`agn tui`	Open the interactive terminal UI.
`agn mcp-server`	Start an MCP (stdio) server exposing workspace tools — for wiring workspace access into MCP-capable agents. Configure with `--workspace-id`, `--channel-name`, `--agent-name`, `--endpoint`; pass the token via the `OA_WORKSPACE_TOKEN` environment variable.
`agn update`	Upgrade the CLI/launcher to the latest release.
`agn version`	Show the version.
`agn help`	Show help.

Global options

Option	What it does
`--config <dir>`	Use a different config directory (default `~/.openagents`).
`--no-update-check`	Skip the automatic update check.

Files

Path	Purpose
`~/.openagents/`	Config home: agents, workspaces, daemon state.
`~/.openagents/env/`	Saved environment variables (API keys) per agent type.