CLI Usage

DimAgent ships a single CLI entrypoint: dim. For the current version number see dimcode on npm.

Help

dim --help

Synopsis

Usage: dim [command] [options]

Run without a command to open the interactive TUI.

Commands:
  tui [--scrollback|--fullscreen] Open the interactive TUI
  tui --scrollback|--fullscreen default
                               Set the default TUI form without opening it
  acp                          Run ACP server over stdio
  exec [--trace[=/abs/path]] [--image <path>] [prompt] Run a one-shot prompt
  exec resume <id|--last>       Resume a session
  image <command>               Generate, edit, or enhance images
  video <command>               Generate, edit, or enhance videos
  speech <command>              Synthesize or transcribe speech
  music generate                Generate music
  audio generate                Generate audio
  asset generate                Generate 3D assets
  motion generate               Generate motion data
  realtime connect              Create a realtime connection
  ocr recognize <input>         Recognize text in images or PDFs
  modality <command>            Manage modality defaults and tasks
  session <command>             Manage sessions
  provider <command>            Manage providers
  model <command>               Manage models and subagent model preference
  remote <command>              Manage Remote host daemon
  auth <command>                Manage auth
  mcp <command>                 Manage MCP servers
  hooks <command>               Review and trust command hooks
  plugin <command>              Manage plugin marketplaces and installs
  usage [--json]                Show DimAgent plan usage
  upgrade                       Upgrade to the latest version
  update                        Alias for upgrade
  version                       Print version
  help                          Print usage

Interactive TUI

dim

The TUI has two forms that share the same sessions and configuration:

Form	Launch	Character	Guide
Fullscreen	`dim tui --fullscreen`	Takes over the terminal window, supports the mouse and `/theme`, restores the terminal on exit	Fullscreen TUI
Scrollback	`dim tui --scrollback`	Writes onto the terminal's main screen; scrolling, search and copy belong to the terminal, and the conversation stays after exit	Scrollback TUI

The launch form resolves in the order --fullscreen / --scrollback flag → the tuiMode setting → fullscreen. Passing both flags is an argument error.

# Set the default form (writes the setting, does not open the UI)
dim tui --scrollback default
dim tui --fullscreen default

# Open and resume a specific session
dim tui --session <session-id>

Use /tui to switch forms while running, with /tui --fullscreen and /tui --scrollback for an explicit target. Switching does not start a new session and does not interrupt a running turn.

Configure approvals from inside the TUI with /approvals or Settings. Use /models, /mcp, and /plugins for runtime configuration.

Permissions, approvals, and sandboxing

These settings control different boundaries:

Entry	Controls	Values or location
`/approvals`	Who decides when the current session reaches an approval	`auto`: allow automatically; `approve-for-me`: let the agent review and ask the user when it cannot decide safely; `normal`: allow read tools and ask the user for writes and commands
`/settings` → Sandbox	The filesystem boundary for tool processes; CLI network access remains unrestricted by default	`workspace-write`, `read-only`, or `off`
`/settings` → Exec command permissions	Default action and matcher rules for shell commands	`ask`, `allow`, or `deny`; saved in `~/.dimcode/v2/permissions.json`

/approvals takes no command arguments; it opens a selector. Approval mode, sandboxing, and Exec command rules apply independently. An auto approval mode does not bypass an access denied by the sandbox.

One-shot Prompt (`dim exec`)

Use dim exec for stdout output in scripts and CI. One-shot runs default to --policy full-access.

# Basic usage
dim exec "Summarize this repo and propose next steps"

# Full access (default for one-shot)
dim exec --policy full-access "hello"

# Safer policies
dim exec --policy workspace-write "Run a focused code review"
dim exec --policy read-only "Review this repo without making changes"

# With verification and one repair pass
dim exec --verify "pnpm test" --repair-attempts 1 "Find the bug and fix it"

# With trace output
dim exec --trace "Find the bug and fix it"
dim exec --trace=/abs/path/to/traces "Find the bug and fix it"

# With image input
dim exec --image screenshot.png "Describe this UI"

# Read from stdin
echo "Review this code" | dim exec --stdin

# JSONL event stream
dim exec --json "Summarize this repo"

# Resume a session
dim exec resume <session-id> "Continue the work"
dim exec resume --last "Continue the work"

Notes:

Available --policy values are read-only, workspace-write, and full-access.
A newly created one-shot session auto-resolves ask permission requests; read-only and explicit deny rules still block denied actions. Resume keeps the existing session permissions.
--allowed-tools <a,b> adds allow rules; --disallowed-tools <a,b> adds deny rules and wins over allow.
--mode agent|plan|goal selects the run mode. Default is agent.
--provider <id> and --model <id> select the model for this run.
--tools <a,b> limits available tools.
--reasoning-effort <effort> applies request-local reasoning when the selected model supports it.
--session-id <id> loads an existing session and errors when it does not exist.

Headless permission options

The current CLI has no --permission option. dim exec selects a permission preset with --policy, then overlays tool rules:

Preset	Filesystem	Network / process	Default tool rules
`read-only`	Read only	deny / deny	Allows `read`; the capability boundary blocks writes and commands
`workspace-write`	Write in the workspace	ask / ask	Allows `read`, `write`, `edit`, and `exec(git *)`; other `exec` calls ask
`full-access`	Full access	allow / allow	One-shot default; does not wait for human approval

Rules merge in this order: preset → --allowed-tools → --disallowed-tools, so deny wins. A tool allow rule cannot cross the preset's filesystem, network, or process capability boundary.

# Read-only review
dim exec --policy read-only "Review this repository"

# Workspace writes, but block shell execution explicitly
dim exec --policy workspace-write --disallowed-tools exec "Update the docs"

# Only expose selected tools; this controls availability, not approval
dim exec --policy read-only --tools read,glob,grep "Audit the code"

`dim exec` option reference

Input and output:

Option	Applies to	Behavior
`<prompt>`	one-shot	Positional input; multiple tokens are joined with spaces
`--stdin`	one-shot	Reads stdin; when a prompt is also present, appends stdin to it
`-`	one-shot	Uses stdin as the complete prompt
`--image <path>`	one-shot, resume	Attaches one local `png`, `jpg`, `jpeg`, `webp`, or `gif` file
`--json`	one-shot, resume	Writes a JSONL event stream to stdout
`--trace[=/absolute/path]`	all `exec` modes	Writes a trace; a custom directory must be absolute and use the `=` form
`--no-hooks`	all `exec` modes	Disables command hooks for the current CLI process

Session and execution:

Option	Applies to	Behavior
`--mode <agent	plan	goal>`
`--session-id <id>`	one-shot entry	Loads an existing session and runs the prompt with its permissions and model
`exec resume <id> <prompt>`	resume	Resumes a specific session
`exec resume --last <prompt>`	resume	Resumes the most recently updated session
`--reasoning-effort <effort>`	one-shot, resume	Values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; applies only when supported by the model
`--rpc`	RPC	Starts stdin/stdout JSONL RPC; default policy is `read-only`, and permission requests use `permission_response`

Model, prompt, and tools:

Option	Applies to	Behavior
`--provider <id>`	new one-shot session	Selects a provider
`--model <id>`	new one-shot session	Selects a model
`--system-prompt <text>`	one-shot	Replaces the complete system prompt
`--append-system-prompt <text>`	one-shot	Appends text after the default system prompt
`--tools <a,b>`	one-shot	Exposes only the selected tools; an unknown tool is an error

Permissions and verification:

Option	Applies to	Behavior
`--policy <preset>`	new one-shot session, RPC	Selects `read-only`, `workspace-write`, or `full-access`; one-shot defaults to `full-access`, RPC to `read-only`
`--allowed-tools <a,b>`	new one-shot session, RPC	Adds allow rules on top of the preset
`--disallowed-tools <a,b>`	new one-shot session, RPC	Adds deny rules and overrides the same allow rule
`--verify <command>`	one-shot, resume	Runs a verifier after the agent completes; repeatable and executed in declaration order
`--repair-attempts <count>`	one-shot, resume	Maximum automatic repair rounds after verification failure; default `0`

Both exec resume and --session-id use an existing session's permissions. Passing --policy, --allowed-tools, --disallowed-tools, --provider, or --model does not rewrite that session. Create a new one-shot session when you need a new permission policy.

`dim auth`

Manages authentication.

dim auth login [--provider dimcode-api-oauth|openai-codex] [--email <email>]
dim auth login --device-login [--provider dimcode-api-oauth] [--email <email>]
dim auth login --provider <id> --api-key <key>
dim auth logout [--provider <id>]
dim auth refresh
dim auth status

Subcommands:

login: authenticate with browser OAuth, device OAuth, or an API key.
logout: remove stored credentials.
refresh: refresh the stored OAuth token.
status: check authentication status.

`dim session`

Manages sessions.

dim session list [--all]
dim session show <id>
dim session delete <id>
dim session export <id>
dim session rename <id> <name>
dim session clean [--older-than <days>] [--keep-last <n>] [--dry-run]

Subcommands:

list: list sessions (current cwd by default, use --all for all).
show: display session details.
delete: delete a session.
export: export session as JSON.
rename: rename a session.
clean: remove old sessions (use --dry-run to preview).

`dim provider`

Manages providers.

dim provider list [--json]
dim provider get <id> [--json]
dim provider add <id> [--api-key <key>] [--base-url <url>] [--model <model>] [--name <name>] [--adapter <adapter>] [--user-agent <value>] [--enabled|--disabled]
dim provider update <id> [--api-key <key>] [--base-url <url>] [--model <model>] [--name <name>] [--adapter <adapter>] [--user-agent <value>|--clear-user-agent] [--enabled|--disabled]
dim provider remove <id>
dim provider enable <id>
dim provider disable <id>
dim provider disconnect <id>
dim provider test <id> [--json]
dim provider switch <id> [--model <model>]

Subcommands:

list: list configured providers.
get: show provider details.
add: add a new provider.
update: update provider settings.
remove: remove a provider.
enable / disable: change provider availability without removing its configuration.
disconnect: remove stored credentials and disable the provider.
test: test provider connectivity.
switch: set the active provider and, when supplied, its default model.

`dim model`

Manages models and subagent model preference.

dim model list [--provider <id>] [--json]
dim model refresh <provider> [--json]
dim model subagent get [--json]
dim model subagent list [--json]
dim model subagent set --provider <providerId> --model <modelId> [--json]
dim model subagent clear [--json]

Use dim provider switch <providerId> --model <modelId> to change the default parent-session model. dim model subagent set changes only the fixed subagent preference; clear restores inheritance from the parent session.

`dim mcp`

Manages MCP servers.

dim mcp list [--json]
dim mcp get <name> [--json]
dim mcp add <name> [--scope user|project] [--force] -- <command> [args...]
dim mcp add <name> --command <cmd> [--args <comma-separated-args>] [--env <KEY=VALUE>] [--scope user|project] [--force]
dim mcp add --transport http <name> <url> [--header <KEY: VALUE>] [--scope user|project] [--force]
dim mcp add-json <name> '<json>' [--scope user|project] [--force]
dim mcp auth list [--json]
dim mcp auth <name> [--json]
dim mcp logout <name> [--json]
dim mcp remove <name> [--scope user|project] [--json]
dim mcp test <name> [--json]
dim mcp toggle <name> --enabled <true|false> [--scope user|project] [--json]

Subcommands:

list: list merged MCP servers, status, scope, transport, and warnings.
get: show MCP server details.
add: add a stdio or HTTP MCP server; writes to user scope by default.
add-json: add an MCP server from one server JSON object.
auth / logout: manage OAuth credentials for HTTP MCP servers.
remove: remove an MCP server; when --scope is omitted, the winning scope is removed.
test: temporarily connect, discover tools, then disconnect.
toggle: enable or disable a server; disabled servers stay in config and leave the runtime toolset.

Examples:

dim mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
dim mcp add --transport http remote https://example.com/mcp
dim mcp add --transport http remote https://example.com/mcp \
  --header 'Authorization: Bearer ${MCP_TOKEN}'
dim mcp add-json remote '{"type":"http","url":"https://example.com/mcp"}'

MCP config lives at ~/.dimcode/v2/mcp.json. Project-level config lives at <project>/.mcp.json. Project entries override user entries with the same server id.

Other CLI commands

dim image generate [--provider <provider> --model <model>] --prompt <prompt> (--out <path>|--out-dir <dir>)
dim image edit [--provider <provider> --model <model>] --prompt <prompt> --image <path> [--image <path> ...] (--out <path>|--out-dir <dir>)
dim image enhance [--provider <provider> --model <model>] --image <path> --operation <operation> (--out <path>|--out-dir <dir>)
dim video generate [--provider <provider> --model <model>] --prompt <prompt> (--out <path>|--out-dir <dir>)
dim video edit [--provider <provider> --model <model>] --video <path> --operation <operation> (--out <path>|--out-dir <dir>)
dim video enhance [--provider <provider> --model <model>] --video <path> --operation <operation> (--out <path>|--out-dir <dir>)
dim speech synthesize [--provider <provider> --model <model>] --text <text> (--out <path>|--out-dir <dir>)
dim speech transcribe [--provider <provider> --model <model>] --audio <path> (--out <path>|--out-dir <dir>)
dim music generate [--provider <provider> --model <model>] --prompt <prompt> (--out <path>|--out-dir <dir>)
dim audio generate [--provider <provider> --model <model>] --operation <video-to-audio|sound-effect> (--out <path>|--out-dir <dir>)
dim asset generate [--provider <provider> --model <model>] (--prompt <prompt>|--image <path>|--asset <path>) (--out <path>|--out-dir <dir>)
dim motion generate [--provider <provider> --model <model>] (--prompt <prompt>|--video <path>|--image <path>|--asset <path>) (--out <path>|--out-dir <dir>)
dim realtime connect --category <category> --input <audio|text|image|video> --output <audio|text|image|video|event>
dim ocr recognize <input> [--provider <provider> --model <model>] [--out-dir <dir>] [--timeout <ms>] [--output-mode <text|layout>] --json
dim modality list [--json]
dim modality get <capability> [--json]
dim modality set <capability> --provider <id> --model <id> [--json]
dim modality unset <capability> [--json]
dim modality task <list|status|wait|cancel> [task-id] [--json]
dim remote daemon [--socket <path>] [--state <path>] [--device-name <name>]
dim remote status [--socket <path>] [--json]
dim remote enable [--socket <path>] [--json]
dim remote disable [--socket <path>] [--json]
dim hooks [list] [--json]
dim hooks disable <index|hash-prefix> [--json]
dim hooks disable --all [--json]
dim hooks enable <index|hash-prefix> [--json]
dim hooks enable --all [--json]
dim export <session_id> [--json|--md] [--compacted] [--format <openai-chat|openai-responses|anthropic|gemini>] [--no-thinking] [--no-tools]

`dim acp`

Starts ACP server mode for editor integrations.

dim acp

See ACP page.

`dim version`

Prints version and runtime details.

dim version
dim --version
dim -v

This command also reports install/update diagnostics for npm and standalone binary installs.

`dim usage`

Shows DimAgent plan usage for the signed-in DimAgent account.

dim usage
dim usage --json

Prints the signed-in account, available model count, credits usage with a progress bar, and window token usage with reset times.
--json prints the raw usage payload as one JSON line.
Requires DimAgent OAuth sign-in; when not signed in, the command exits with an error and points to dim auth login.

`dim upgrade`

Upgrades the standalone binary install. dim update is an alias for dim upgrade.

# Check for updates
dim upgrade --check

# Upgrade to latest
dim upgrade

# Quiet or background mode
dim upgrade --quiet
dim upgrade --background

Flags:

--check: check for updates and exit.
--quiet, --background: suppress output for background updates.

npm/pnpm/yarn/bun installs should be upgraded with the package manager:

npm install -g dimcode@latest

Auto-update

dim checks for updates and only notifies you; it never installs one on its own. Apply an update with dim upgrade (or your package manager).

Set DIMCODE_DISABLE_AUTOUPDATE=1 to disable update checks.
Set DIMCODE_AUTOUPDATE=0 to disable update checks (same effect as DIMCODE_DISABLE_AUTOUPDATE=1).
Standalone binary update metadata is stored under ~/.dimcode/dimcode/bin/binary-upgrade.json.

Keyboard Shortcuts

Shared by both forms:

Ctrl+P: command palette
Enter: send
Shift+Enter or Ctrl+J: new line
Tab: switch AGENT / PLAN mode
Ctrl+O: open or close the background-work panel
Ctrl+V: paste a clipboard image
Esc: interrupt the running turn
Ctrl+C: close the top overlay / clear input, press again to exit

Timeline and new-session bindings differ per form (Mod+T / Mod+N in fullscreen, Ctrl+T / Ctrl+N in scrollback). Full tables live in Fullscreen TUI and Scrollback TUI.

Slash Commands

Command	What it does
`/new`	New session
`/resume`	Open the session list and resume (alias `/sessions`)
`/timeline`	Jump to a user message
`/compact`	Compact the conversation
`/export`	Export the current session
`/agent`	Switch to agent mode
`/plan`	Switch to plan mode
`/goal`	Switch to goal mode
`/external-agents`	Manage external agents (alias `/agents`)
`/skills`	Open the skills picker
`/approvals`	Tool approvals (`auto` / `approve-for-me` / `normal`)
`/connect`	Connect a provider or add a custom/local one
`/models`	Select provider and model
`/effort`	Set the reasoning level (alias `/reasoning`; in scrollback it is adjusted inline in `/models` with `←→`)
`/mcp`	Manage MCP connectors and advanced settings
`/plugins`	Manage plugins such as Serper Search
`/language`	Switch UI language
`/theme`	Toggle light/dark theme (fullscreen only)
`/settings`	Open the settings dialog
`/debug`	Print diagnostics for the current session
`/tui`	Switch between the fullscreen and scrollback forms
`/exit`	Exit

The scrollback form adds /keys (commit the full key reference into the scrollback) and /queue (manage messages queued during a run).

Data Locations

DimAgent v2 stores local data under ~/.dimcode/v2/ by default:

dimcode.sqlite: main storage database (sessions, providers, etc.)
credentials.json: global credentials
credentials/<providerId>.json: per-provider credentials
mcp.json: MCP server configuration

Use DIMCODE_HOME=/absolute/path to relocate the base directory.

CLI Usage

Help

Synopsis

Interactive TUI

Permissions, approvals, and sandboxing

One-shot Prompt (dim exec)

Headless permission options

dim exec option reference

dim auth

dim session

dim provider

dim model

dim mcp

Other CLI commands

dim acp

dim version

dim usage

dim upgrade

Auto-update

Keyboard Shortcuts

Slash Commands

Data Locations

One-shot Prompt (`dim exec`)

`dim exec` option reference

`dim auth`

`dim session`

`dim provider`

`dim model`

`dim mcp`

`dim acp`

`dim version`

`dim usage`

`dim upgrade`