CLI Reference¶
Every subcommand runs from inside a Runa app (created with runa new), except runa new itself.
runa new [NAME]¶
Scaffold a new application at ./NAME, with the conventional layout. See
Getting Started. Omit NAME to scaffold the current directory in place
instead of creating a subdirectory.
runa generate KIND NAME¶
Generate scaffolding inside an existing app:
runa generate agent MyAgent --model gpt-5.4-nano # app/agents/my_agent.py, evals/my_agent.jsonl
runa generate tool MyTool # app/tools/my_tool.py
runa generate guardrail MyCheck # app/guardrails/my_check.py
runa generate prompt my_agent # app/prompts/my_agent.md
runa generate evaluation my_agent # evals/my_agent.jsonl, for a hand-written agent
agent's NAME must be UpperCamelCase ending in Agent, for example MyAgent. That is the one
naming convention this command enforces. Both the generated file and the class's name
attribute are derived from it via snake_case (MyAgent becomes app/agents/my_agent.py, with
name = "my_agent"). There is no separate --name to pass. --model is required.
--instructions, --tool, --guardrail, --memory, --knowledge, and --compact stay
optional.
runa chat [AGENT_NAME]¶
Chat with an agent, or inspect past sessions. See Sessions and Chat.
runa chat support_agent # start (or resume) a chat
runa chat support_agent --continue # resume the most recent session
runa chat support_agent --resume [SESSION_ID] # resume a chosen/given session
runa chat support_agent --session SESSION_ID # pin an exact session id
runa chat --list # list every session
runa chat --show SESSION_ID # replay one session's history
runa test¶
Run every test_* function under tests/.
runa eval [AGENT_NAME]¶
Run every dataset under evals/ against its agent, or, with AGENT_NAME (the Agent's declared
name, for example support_agent), just that one. See Evaluation.
runa eval # grade every evals/ dataset
runa eval support_agent # grade one agent's dataset
runa eval --add TRACE_ID [--expected TEXT] # add a traced run as a case
runa traces SUBCOMMAND¶
Inspect this app's traces in runa.db. See Tracing and Hooks.
runa traces list # most recent traces
runa traces errors # most recent traces that errored
runa traces show TRACE_ID # one trace's full span tree
runa serve¶
Serve this app's agents over HTTP. See Deployment. Needs the serve extra
(uv add "runa-ai[serve]"), not installed by a plain runa-ai install.
runa serve # http://127.0.0.1:8000, bearer auth
runa serve --host 0.0.0.0 --port 8000 # reachable from outside a container
runa serve --no-auth # local use, no token required
One process, no worker flag: for several workers, run uvicorn asgi:app --workers 4 against the
scaffolded asgi.py, which is the address a supervisor needs.
Requires RUNA_API_KEY and refuses to start without it, unless --no-auth is passed. Routes:
GET /health (unauthenticated), GET /agents, POST /agents/{name}/runs and
POST /agents/{name}/runs/stream. A run that pauses for approval resumes through the same route
it paused on, by posting its state back with the decisions a human made.
runa ui¶
Serve a local, read-only dashboard over runa.db: Agents, Sessions, Traces, and Evaluations.
Needs the ui extra (uv add "runa-ai[ui]"), not installed by a plain runa install.
The Agents page lists the app as it was imported when the dashboard started, not as it is on
disk: a page view never re-runs your main.py. Editing app/agents/ takes a restart, the same
as runa serve.
Exit Codes¶
runa eval and runa test exit 1 if any case or test failed, 0 otherwise, safe to wire into
CI. Everything else exits 1 only on an operator error (a mistyped id, running outside a Runa
app), printing a clean message instead of a traceback.