CLI Overview

Architecture at a glance

The Dreadnode terminal client is a full-screen Textual app that talks to the Python agent server. You start it once, it connects to a running server or auto-starts the default local one, and then all chat, sessions, and runtime metadata flow through that server connection.

Start the CLI

$ dreadnode
opens the Textual client

$ dreadnode tui
opens the Textual client explicitly

Use dreadnode serve when you want a long-lived local runtime for another client, test harness, or separate terminal:

$ dreadnode serve --host 127.0.0.1 --port 8787 --working-dir .

Startup flags

Flag	Arguments	Description
-s, --server	<url>	Connect to an existing runtime server instead of auto-starting the default local one
-p, --platform	<url>	Platform API URL override used for authentication and profile selection

Authentication

Use dreadnode login to save a platform profile before launching the client. If you omit the API key, the CLI starts a browser-based device login flow.

$ dreadnode login
$ dreadnode login dn_key_... --server http://localhost:3000

Once you are inside the Textual client, the in-app /login command remains available.

Serve subcommand flags

Use dreadnode serve when you want to run the runtime server without launching the TUI.

Flag	Arguments	Description
--host	<host>	Host interface for the local runtime server
--port	<port>	Port for the local runtime server
--working-dir	<path>	Working directory for the runtime server
--platform-server	<url>	Platform API base URL for the local runtime
--api-key	<key>	Platform API key used by the runtime server
--organization	<org>	Default organization key for the runtime server
--workspace	<ws>	Default workspace key for the runtime server
--project	<proj>	Default project key for the runtime server
--verbose	—	Enable verbose trace logging for the local server

Package upload commands

The CLI can also publish reusable assets to the platform OCI registry:

$ dreadnode capability push ./packages/capabilities/web-security
$ dreadnode dataset push ./seed-data/datasets/vulnerability-reports
$ dreadnode model push ./seed-data/models/vuln-classifier
$ dreadnode task push ~/projects/security-tasks/terminal-bench-tasks/security-bandit-bandit-00

Use dreadnode task push for task-style environment directories that contain a task.yaml and a runnable environment definition such as docker-compose.yaml.

For registry-backed package management, the CLI now also supports read and delete flows directly:

$ dreadnode capability list
$ dreadnode capability get [email protected]
$ dreadnode capability update [email protected] --public
$ dreadnode capability delete [email protected]
$ dreadnode dataset list
$ dreadnode dataset get [email protected]
$ dreadnode dataset delete [email protected]
$ dreadnode model list
$ dreadnode model get [email protected]
$ dreadnode model delete [email protected]
$ dreadnode task list
$ dreadnode task get security-bandit-bandit-00@latest
$ dreadnode task update security-bandit-bandit-00@latest --public
$ dreadnode task delete security-bandit-bandit-00@latest

Datasets and models are immutable once published. To “update” them, push a new version. Capabilities and tasks support metadata updates for visibility through the update subcommand. Task refs use NAME@latest.

Hosted training commands

The CLI also exposes hosted training submission and management through dn train. See Training for the SFT and RL command surface.

Hosted optimization commands

The CLI also exposes hosted optimization submission and management through dn optimize. See Optimization for the hosted GEPA command surface.

AIRT commands

The CLI also exposes AIRT assessment management and analytics through dn airt. See AIRT for the assessment, report, trace, and project-summary command surface.

Worlds commands

The CLI also exposes Worlds manifest, trajectory, and job management through dn worlds. See Worlds for the full control-plane command surface.

Platform URL overrides

Use the --platform flag or the DREADNODE_SERVER environment variable to target a non-default platform before the auth modal opens (for example, a local web app):

$ dreadnode --platform http://localhost:3000
$ DREADNODE_SERVER=http://localhost:3000 dreadnode

Precedence order:

1. --platform flag
2. DREADNODE_SERVER environment variable
3. Active profile URL
4. Default platform URL

In-app commands

The first Textual release is intentionally server-first and focused on the runtime session loop.

Command	Arguments	Description
/help	—	Show the in-app command set
/new	—	Start a fresh runtime session
/reset	—	Reset the active runtime session
/sessions	—	List active server sessions
/use	<id>	Switch to an existing server session by id prefix
/delete	<id>	Delete a server session by id prefix
/agents	—	List agents exposed by the connected runtime
/agent	<name>	Start a new session bound to the named agent
/model	[provider/model]	Get or set the active model for future turns
/runtime	—	Refresh runtime metadata from the connected server
/login	[api-key] [--server <url>]	Authenticate with the platform and restart the runtime
/logout	—	Delete the active profile and fall back to local-only runtime
/whoami	—	Display the current identity and platform server
/workspaces	—	List workspaces for the authenticated user
/projects	[workspace]	List projects in a workspace
/models	—	List platform models
/runtimes	—	View interactive runtimes in the current workspace (/rt)
/hub	—	Browse datasets, models, tasks, and capabilities
/secrets	—	View configured secrets and provider presets (/sec)
/rename	<title>	Rename the current session
/tools	<compact|expanded>	Control tool result rendering (one-line vs detailed)
/export	[filename]	Export the current session transcript
/traces	—	Browse traces for the current project
/sandboxes	—	Monitor your sandboxes
/evaluations	—	View evaluation jobs
/console	—	View backend logs
/copy	—	Copy the last assistant message (or press y)
/quit	—	Exit the client (/exit, /q, or bare exit/quit/:q)
!<command>	<command>	Run a shell command on the connected runtime
@<agent>	<agent>	Route a prompt to a specific agent from the current capability

Keybindings

Keybinding	Description
Ctrl+B	Toggle the sidebar
Ctrl+T	Open traces
Ctrl+S	Open sandboxes
Ctrl+E	Open evaluations
Ctrl+Y	Open runtimes
F5	Open console logs
F6	Open secrets
F7	Open hub
F8	Open environments
Ctrl+N	Start a new session
Ctrl+R	Reset the active session
j / k	Scroll the conversation up or down
g / G	Jump to the top or bottom
y	Copy the last assistant message
?	Show in-app help

Environment screen shortcuts

Use the Environments screen (F8 or /environments) to browse tasks and start sandboxes.

Keybinding	Description
s / Enter	Start the selected environment
c	Copy the rendered instruction to the clipboard

Tool display and streaming behavior

The chat panel now follows deterministic event boundaries:

• Assistant text streams live in the draft area during generation.
• Draft text is committed once at stable boundaries (for example when a tool starts or the turn ends).
• Tool calls render as one-line rows (tool(arg) — summary) so the timeline stays compact.
• Use /tools expanded when you want tool rows to include a second detail line with the raw result.
• Use /tools compact to return to summary-only tool rows.

Blocking states and noise filtering

• heartbeat events update liveness internally and do not add transcript noise.
• permissionrequired and userinputrequired events move the UI into blocking mode and disable composer input until the turn can resume.

Pre-1.0 note

The terminal client is still evolving quickly. The first Textual version focuses on the server session loop first, then broader platform workflows will be layered back in.