Skip to content

CLI

The dam CLI lets you manage agents, attach to terminal sessions, transfer files, wire up connections, and more — all from your local machine.

Installation

npm install -g @dam-agents/cli

Requires Node 20 or later.

Configuration

dam config set server https://dam.res.ibm.com/

This is the IBM hosted deployment. On your own deployment, set server to its URL.

server is the only key dam config set accepts. Config is stored at ~/.config/dam/config.toml (or $XDG_CONFIG_HOME/dam/); credentials are stored separately at ~/.local/state/dam/auth.toml (mode 0600).

Environment variables:

Variable Purpose
DAM_SERVER Override the configured server URL
DAM_TOKEN Use a bearer token or pk_… API key directly (bypasses login, useful for CI). Used verbatim and never refreshed

Precedence: CLI flag > environment variable > config file.

Global flags:

  • --server <url> — override the configured server URL for a single call. Available on every networked command except dam auth status and the dam auth token subcommands, which use the configured active host.
  • --json — emit machine-readable JSON instead of the default table/summary. Available on most read and mutate commands; handy for scripting. Not available on auth login, auth logout, auth status, auth token revoke, ping, dam ssh, chat, file get, file put, config set, agent create-interactive, satellite mcp, or satellite shell. (file list does have it.)

Precedence for the server URL is flag > DAM_SERVER > config file > error — there is no default server.

Authentication

dam auth login       # Authenticate via OAuth 2.0 Device Authorization Grant
dam auth logout      # Clear local credentials and best-effort revoke the refresh token
dam auth status      # List configured hosts, their credential source, and the active server

Login uses the OAuth 2.0 Device Authorization Grant — you'll see a URL and code to confirm in your browser. Tokens are stored locally and refreshed automatically.

dam auth login --server https://host   # set the active host while logging in
dam auth login --no-browser            # print the verification URL instead of opening a browser
dam auth login --force                 # skip the re-login confirm when already logged in
dam auth logout --server https://host  # log out of a specific host (defaults to the active one)

For CI/headless use, set DAM_TOKEN=<bearer> instead of logging in. There is no --token flag, to avoid leaking tokens into shell history.

API keys (auth token)

For headless/CI use you can mint long-lived API keys:

dam auth token create --name ci-key                 # mint a key; plaintext printed ONCE on stderr
dam auth token create --name ci --scope agents:operate --agent agent-123 --expires 2026-12-31T00:00:00Z
dam auth token list                                 # list your keys (plaintext never shown again)
dam auth token revoke key-abcdef12                  # revoke a key; rejected on the next request
  • --name <name> is required. --scope <scope...> and --agent <agent-id...> each take several values after one flag (--scope agents:read agents:operate), and repeating the flag works too — both forms add up. Omit --scope and you get agents:operate alone; a key always carries at least one scope. The valid values are agents:read, agents:operate, agents:manage, credentials:read, and credentials:manage. --agent defaults to every agent you own.
  • --expires <iso> takes an ISO 8601 timestamp.
  • The plaintext token is shown only at creation — copy it immediately, it cannot be recovered.
  • Minted keys carry a pk_ prefix and can be used directly as DAM_TOKEN. API-key principals cannot mint further keys.

Commands

Agent Management

dam agent list                                   # List your agents (default command)
dam agent get <name-or-id>                        # Show one agent's details
dam agent create <name>                          # Create an agent
dam agent create <name> --provider <id-or-name> --wait  # Pick its provider; block until it reaches running
dam agent create-interactive                     # Interactive setup: name + template + credentials (TTY-only)
dam agent delete <name-or-id>                     # Delete an agent and all its persistent data (confirms)
dam agent delete <name-or-id> --yes               # Delete without confirmation
dam agent restart <name-or-id>                    # Restart the agent (persistent volumes survive)
dam agent update <name-or-id> --harness <name> --model <provider>/<model>  # Set its default harness and model
dam agent models <name-or-id>                     # List the models its providers offer
dam agent disable <name-or-id>                    # Put it to sleep; nothing wakes it until you enable it
dam agent enable <name-or-id>                     # Let it wake again on its next use
  • create flags: --template <id> (defaults to the install's default template), --provider <id-or-name> (defaults to your preferred provider — the one dam connection list --providers marks preferred), --description <text>, --env KEY=VAL (repeatable), --wait, --timeout <seconds> (default 120), --json.
  • --provider names a model-provider connection, by connection id or by a name unique among your providers — dam connection list shows both. An unknown, ambiguous, non-provider or inactive --provider is refused before the agent is created, so a wrong flag costs nothing. Resolving a name reads your connections, which needs credentials:read; pass a connection id to create with agents:manage alone. dam agent create-interactive collects the provider for you and needs neither flag.
  • The harness is picked per session, so create doesn't take one. update sets the agent's defaults: --harness, --model (named the way dam agent models lists them), --setting id=value (repeatable), and --kind chat|channel|scheduled to say which default you're setting (default chat). It also grants or removes providers with --provider / --remove-provider; removing one that a default used moves that default and says so.
  • A disabled agent reads disabled in list and get, and nothing — a schedule, a message, a session — wakes it until dam agent enable.
  • --wait is available on create and restart; pair with --timeout to change the 120s default.
  • --json on list, get, delete, and restart for machine-readable output.

Templates

dam template list    # List agent templates available on the active host

Templates are read-only from the CLI — your operator decides which ones the host offers.

Connections

Connections are reusable OAuth/credential bindings (GitHub, MCP servers, custom-header API keys) that you create once — they're yours alone — then grant to any of your agents.

dam connection templates                          # List provider templates you can create from
dam connection list                               # List your connections
dam connection list <agent>                       # List the connections granted to one agent
dam connection connect <provider-or-url>          # Create a connection from a template or MCP server URL
dam connection update <id-or-name>                # Rotate a connection's stored secret (on a DAM web page)
dam connection reauth <id-or-name>                # Re-run login and consent for an OAuth connection
dam connection test <id-or-name>                  # Re-check a connection's stored credential
dam connection disconnect <id-or-name>            # Remove a connection (deletes the stored credential; confirms, -y to skip)
dam connection grant <agent> --connection <id>    # Grant one or more connections to an agent (repeatable; at least one)
dam connection revoke <agent> --connection <id>   # Revoke connections from an agent (repeatable; at least one; idempotent)

connection connect takes either a provider template id (see dam connection templates) or an MCP server URL (https://…). dam connection templates lists only the ids connect accepts directly — MCP-category templates are left out on purpose, since MCP servers are added by URL instead. Useful flags:

  • --name <name> — connection name (defaults to a slug of the template name or the MCP host)
  • --auth oauth|none — MCP auth mode (auto-detected by default)
  • --no-browser — print the consent or secret-entry link instead of opening a browser
  • --prompt — type a missing secret at a hidden terminal prompt instead of on a web page
  • --timeout <seconds> — how long to wait for OAuth authorization (default 300)
  • -c, --config <key=value> — set an optional template config input (repeatable), e.g. --config model=premium-shell; values are validated against the template's declared inputs.

Provider templates also declare their own required inputs, each exposed as its own flag — e.g. --host/--url, --client-id/--client-secret, --header-name/--value/--value-format/--env-name, --ca-data, or Object Storage's --endpoint/--bucket/--access-key-id/--secret-access-key. Run dam connection connect <provider> --help for the set that applies. Leave a secret off and the command opens a DAM web page where you enter it (sign in as the same user; the link works once), then waits for it to be saved; other missing inputs are prompted for.

connection update replaces a connection's stored secret in place. What that means depends on the connection: the injected value for an API key or custom-header integration, or an OAuth connection's own client secret where it carries one. A connection that stores no credential has nothing to update. Without --value, update opens a DAM web page where you enter the new secret — a multi-line key works there too — and waits until it's saved. Pass --prompt to type it at a hidden terminal prompt instead (an OAuth client secret is always asked for there), --no-browser to print the link, or --value <secret> from a script.

An Object Storage connection holds a key pair rather than one secret, so update rotates both at once: pass --access-key-id and --secret-access-key instead of --value, or enter both on the page. The new pair is checked against the storage endpoint first, and a pair it rejects replaces nothing.

Use update to replace a secret you hold, and reauth to replace expired OAuth tokens.

connection reauth re-runs login and consent for an OAuth connection, replacing only its tokens: the connection keeps its identity and every agent grant it already has, so nothing needs re-granting afterwards. Reach for it when a connection shows expired, or to re-consent after its template gained scopes. It opens a browser and waits for you to authorize:

dam connection reauth github
dam connection reauth conn-61cc7b9137b0 --no-browser   # print the URL instead of opening it

Flags: --no-browser, --timeout <seconds> (default 300), --json, --server <url>. A connection that stores its own secret has no login flow — reauth refuses it and points you at connection update instead.

Satellites

Experimental

Satellites are experimental, and the commands below may change.

A satellite is a machine outside DAM, such as your laptop or a build box, that offers tools to your agents. You start it on that machine with dam satellite. It connects out to DAM, so nothing has to reach in. See Satellites.

dam satellite mcp -- <command...>          # Offer the tools of an MCP server started on this machine
dam satellite mcp --url localhost:8080     # ...or of one that's already running
dam satellite shell "<pattern>"            # Offer a fixed set of permitted commands as one tool
dam satellite list                         # Your satellites, with their state, tools and agents
dam satellite grant <satellite> <agent>    # Let an agent call a satellite's tools
dam satellite revoke <satellite> <agent>   # Stop it again
dam satellite jobs <satellite>             # The calls a satellite has run
dam satellite cancel <satellite> <job>     # Ask a satellite to stop a job
dam satellite rm <satellite>               # Remove a satellite and every grant to it (confirms)
  • mcp and shell stay in the foreground and serve until you stop them. The first Ctrl+C drains, so running jobs finish and report back. A second Ctrl+C kills them. Both take --name (the name agents see), --description and --max-concurrent. Without --name, the satellite is named after the server or command it offers, or user@hostname.
  • mcp starts the server you name after --, or forwards to one already listening with --url. A bare host:port means http://host:port/mcp. --header "Name: value" (repeatable) is sent to a --url server, and --cwd sets a started server's working directory. A started server inherits your shell's environment. Its tools are offered as they are, and the server decides what each call may do.
  • shell takes one usage line per permitted command, as an argument or on stdin. A # starts that line's description, and a trailing [max=N timeout=D cwd=PATH] sets limits for that command alone. --cwd and --timeout set the defaults. The machine refuses any call that matches none of the lines. That text is the whole allowlist, so to change it, restart the command:

    dam satellite shell --name gpu-box --cwd /srv --timeout 6h <<'EOF'
    ./process.sh (sales.db|events.db)  # Process a database
    ./train.sh ./data/**/*.db          # Train  [max=1 timeout=2h]
    EOF
    
  • No agent can call a satellite's tools until you grant it the satellite. grant and revoke take any of your agents by name or ID.

  • cancel only asks: a command that's already running may still finish.
  • rm doesn't stop commands already running on the machine. The running dam satellite stops taking new work, and you can start it again to register it anew. It confirms on a TTY; pass --yes non-interactively.
  • list and jobs take --json.

Network access

Per-agent rules that pre-approve the external hosts an agent may reach.

dam network list <agent>                               # List network access rules
dam network create <agent> --host api.example.com      # Add a rule (default method/path '*', verdict allow)
dam network update <rule-id>                           # Update an existing rule
dam network revoke <rule-id>                           # Remove a rule
dam network preset <agent>                             # Show the agent's effective preset
dam network apply-preset <agent> --preset <none|trusted|all> [-y]  # Apply a network preset ('all' needs -y when scripting)
dam network trusted-hosts                              # Platform-wide hosts seeded by the 'trusted' preset

network create flags: --host <h> (required), --method <m> (default *), --path <p> (default *), --verdict allow|deny (default allow), -y, --yes (skip the path-level restart confirmation), --json. A rule for a service that isn't on port 443 can't be created from the CLI — add it under Network access in the agent, where the host field takes host:port.

network update flags: --method <m>, --path <p>, --verdict allow|deny, -y, --yes, --json — partial, so pass only the fields you want to change. Updating a rule marks it manual.

apply-preset replaces only the rules the preset put there — rules you created by hand and rules derived from connections are preserved. The CLI prints that reminder before applying.

A narrowed rule restarts the gateway

A rule that specifies a non-wildcard method or path needs path-level enforcement, which restarts the agent's network gateway (~5–15s) — the agent keeps running, but its outbound requests are briefly interrupted. The CLI confirms first; -y skips the prompt. Host-only rules don't restart anything. See Network & Approvals.

Skills

Browse skill sources and manage the skills installed on an agent.

dam skill source list                                  # List connected skill sources
dam skill source add <git-url>                         # Register a skill source from a git URL
dam skill source remove <id>                           # Remove a source you added (installed skills remain)
dam skill source refresh <id>                          # Drop a source's scan cache so the next catalog re-scans upstream
dam skill catalog <source>                             # Scan a source's available skills
dam skill catalog <source> --agent <ref>               # Annotate install status against an agent
dam skill list <agent>                                 # List the skills on an agent
dam skill install <agent> --source <id-or-url> --name <skill>   # Install (or update) a skill (both flags required)
dam skill uninstall <agent> --source <id-or-url> --name <skill>   # Remove a skill (both flags required)
dam skill publish <agent> --name <skill> --source <id-or-url> [--title <t>] [--body <b>]   # Publish a skill as a PR (--name/--source required; --title/--body optional)
  • source add also takes --name <name> and --path <subdir> to scan only a subdirectory of the repo. The name defaults to the repository's owner and name — https://github.com/acme/skills becomes acme/skills. Slashes are kept; unlike connection names, skill-source names aren't slugified. On github.com the owner and name are lowercased, so a URL you pasted with capitals gives a lowercase name. You can also paste a URL straight out of the browser: a …/tree/<ref>/<subdir> link supplies the subdirectory for you, so you don't have to pass --path as well. On a TTY you're prompted with that value pre-filled.
  • source list --agent <ref> additionally includes sources declared by the agent's template. source remove confirms on a TTY — pass -y, --yes non-interactively.
  • catalog --agent <ref> annotates each skill as not-installed / installed / update-available and scans private sources through that agent's pod.
  • install installs the version the source was last scanned at, not whatever its repo holds this second — there is no --version flag and no separate update verb; re-running install updates in place. To pick up a commit pushed in the last few minutes, run source refresh <id> first so the next scan re-reads upstream.
  • publish works only on standalone (locally-authored) skills, and only against GitHub sources. Its --source is the repo to open the pull request against — not where the skill came from, as it means on install/uninstall, since a standalone skill has no origin source.

Channels

Bind an agent to a Slack conversation.

dam channel available                                       # List enabled messenger providers
dam channel list <agent>                                    # Bindings, with each Slack binding's ambient state
dam channel slack connect <agent> --channel-id <C0…>            # Bind the channel (mentions-only)
dam channel slack connect <agent> --channel-id <C0…> --ambient  # Bind with ambient mode on
dam channel slack disconnect <agent>                        # Unbind (when only one channel is connected)
dam channel slack disconnect <agent> --channel-id <C0…>     # Unbind one of several connected channels
  • A conversation may hold several agents, and an agent may hold several Slack bindings at once — the pairing is what's unique, so the same agent can't join one conversation twice. disconnect takes --channel-id to say which binding to release; it is required once the agent has more than one connected, and optional when it has just one. disconnect is idempotent — an agent that isn't connected exits 0.
  • The binding is the authorization: anyone Slack admits to the conversation drives the agent, and every turn runs under the agent's own credentials. There is no per-person mode and no allow-list. See Who can drive the agent.
  • --ambient starts the binding in ambient mode — the agent reads along and may reply without being mentioned. Omit it and ambient is off. Against a server too old to understand ambient, the connect fails loudly rather than silently landing mentions-only.
  • Re-running connect for the same agent and channel updates that binding in place, which is how you change ambient mode from the CLI — no disconnect needed. Connecting a further channel to the same agent adds a binding instead of replacing one, and so does connecting a different agent to a channel that already has one — a conversation can hold several agents (see Slack). Note the in-chat /dam bind is stricter: it refuses an agent already connected to that conversation rather than updating it.
  • There's no default subcommand. Which agent unnamed mentions reach is set in-chat with /dam default <agent>.
  • dam channel list prints TYPE, IDENTIFIER, and AMBIENT. Telegram rows show no identifier or ambient state — the bot token is write-only, and Telegram's ambient mode is switched in the chat with /ambient.
  • Binding from the CLI doesn't link your Slack identity, which the in-chat /dam unbind, /dam ambient on|off, /dam default <agent>, /dam whisper <agent> on|off, /dam ignore, /dam unignore, and /dam delete all require. Run /dam login once in the channel. Driving the agent itself never needs a link. Your agent needs it, though, to post on its own into a channel it isn't connected to: it may reach only channels you're a member of, and until you've linked it can't reach any.
  • Telegram chats bind in-chat via /bind — Telegram's commands are bare, not namespaced under /dam — rather than through this command group.

Approvals

The human-in-the-loop inbox — requests your agents are waiting on (held tool calls, network prompts).

dam approval list                                      # Pending requests across all your agents
dam approval list <agent> --status all                 # Include resolved and expired, for one agent
dam approval approve <id>                               # Approve — DURABLE: writes a permanent allow rule
dam approval approve <id> --once                        # Allow only this held call
dam approval approve <id> --entire-host                 # Allow the whole host (network requests only)
dam approval deny <id>                                  # Deny — DURABLE: writes a permanent deny rule
dam approval deny <id> --once                           # Deny only this held call
  • list flags: --status pending|resolved|expired|all (default pending), --limit <n> (1–500).
  • --once and --entire-host are mutually exclusive.
  • The web UI offers the same choices in Activity under different names: bare approve is Allow permanently, --once is Allow once, --entire-host is Allow all of <host>, deny --once is Deny this request, and bare deny is Deny permanently.

Bare approve and deny are durable

For a network request, dam approval approve <id> writes a permanent allow rule — egress to that host/method/path stays open, and the rule then appears in dam network list <agent>. deny is the mirror. Use --once when you only mean to release (or refuse) the held call; the same request shape re-prompts next time.

Tool-call approvals never write an egress rule — the harness owns its own permission persistence, and --entire-host falls back to the durable approve there.

  • --once and --entire-host are mutually exclusive.

Schedules

Manage time-triggered tasks (schedules) attached to an agent — the CLI equivalent of the agent's Schedules panel.

dam schedule list <agent>              # List the schedules attached to an agent
dam schedule get <schedule-id>         # Show one schedule, expanded
dam schedule create <agent> --name <name> --task <task> --daily 22:00   # Create an RRULE schedule
dam schedule create <agent> --name <name> --task <task> --once --at "2026-11-05 09:00"   # A one-time task (or --now)
dam schedule update <schedule-id> --task "New prompt"   # Update name/task/recurrence/timezone/etc.
dam schedule enable <schedule-id>      # Enable a schedule (idempotent)
dam schedule disable <schedule-id>     # Disable a schedule (idempotent)
dam schedule delete <schedule-id>      # Delete a schedule (idempotent — unknown ids exit 0)
dam schedule reset-session <schedule-id>   # Reset the session a continuous schedule reuses

create requires --name <name> and --task <task> (the prompt run each tick), plus one recurrence. Choose the recurrence with exactly one of:

  • --daily <HH:MM> — run daily at a 24-hour time
  • --every <interval> — run every N minutes (Nm) or hours (Nh)
  • --rrule <body> — a raw RFC 5545 RRULE body (e.g. FREQ=WEEKLY;BYDAY=MO;BYHOUR=7;BYMINUTE=0)

Or pass --once with --at "YYYY-MM-DD HH:MM" (in --timezone) or --now for a task that runs one time, in a fresh session. A one-time task takes none of the recurrence, quiet-window, session-mode or precheck flags.

Additional flags (on both create and update):

  • --weekdays <days> — limit --daily/--every to specific days, e.g. MO,WE,FR. Can't combine with --rrule, whose body carries its own BYDAY. On update it only applies while you're rebuilding the recurrence, so pass it together with --daily or --every — you can't narrow the days of an existing schedule on its own
  • --timezone <tz> — IANA timezone (defaults to the host's zone)
  • --quiet-window <HH:MM-HH:MM> — suppress fires inside a window (repeatable)
  • --session-mode <fresh|continuous> — new session per fire, or one shared session. Defaults to fresh on create; on update, omitting it leaves the stored value unchanged
  • --harness <name> / --model <provider>/<model id> / --setting id=value — what the schedule's sessions run on, instead of the agent's defaults
  • --precheck <command> — a shell command that decides whether each fire actually runs. See Prechecks. update also takes --precheck-none to remove one
  • --json — emit the schedule as JSON (available on every subcommand)

On update, --quiet-window replaces all existing windows rather than adding to them, and at least one field must be passed. Legacy cron schedules are read-only — recreate them as RRULE schedules to edit.

delete takes -y, --yes to skip the confirmation prompt and requires it on a non-TTY — without it the command refuses and exits non-zero whatever the id. Past the confirmation it's idempotent: an unknown id exits 0. enable/disable are idempotent too and need no confirmation. Schedule ids come from dam schedule list.

get adds a Stopped line, with the reason, for an enabled schedule that has no next run: a rule that has run out of occurrences, say, or quiet hours that cover every remaining one.

There's no CLI command to fire a schedule on demand. Use Run now in the schedule's ⋯ menu in the agent's Schedules panel.

Terminal Sessions

dam chat <agent>                       # New terminal session
dam chat <agent> --continue            # Reattach to the most recent terminal session
dam chat <agent> --resume <session-id> # Resume a specific session
dam chat <agent> --reset               # Kill the existing PTY and start fresh
dam session list <agent>               # List all sessions for an agent (`dam session <agent>` works too)

dam chat connects your terminal directly to the agent's interactive TUI over WebSocket. Keystrokes (including Ctrl+C) pass through to the remote harness, so to leave, close the terminal. If the connection drops, the CLI reconnects to the same session by itself; when the session ends or it can't reconnect, it prints a dam chat <agent> --resume <id> command. It prints that command when it attaches too, and waits a few seconds first — press Enter to connect at once, or pass --no-pause. Short flags: -c (--continue), -r (--resume).

Headless runs

Where dam chat gives you an interactive terminal, dam run gives you one prompt and one answer on stdout — the shape you want in a script or a pipeline.

dam run <agent> -p "summarize today's open PRs"   # Submit a prompt, stream the answer
dam run <agent> --prompt-file task.md             # Read the prompt from a file
cat task.md | dam run <agent> --prompt-file -     # ...or from stdin
dam run <agent> -p "..." --session <id>           # Continue an existing session
dam run <agent> -p "..." --async                  # Exit once the run starts; prints its session id
dam run get <agent> <session-id>                  # Read a run's recorded result
dam run get <agent> <session-id> --wait           # ...blocking until the turn finishes
dam run cancel <agent> <session-id>               # Cancel a run in flight
  • Pass exactly one of -p, --prompt and --prompt-file — passing both, or neither, is an error. A promptless dam run refuses rather than waiting on stdin, so it can't hang a script by accident.
  • The answer goes to stdout; progress, warnings, and the closing stopReason go to stderr, so redirecting stdout gives you just the reply.
  • Exit codes carry the outcome. 0 means the agent finished its turn normally; a run that stopped for any other reason, a run whose result you fetched and found stopped, and a timeout each exit non-zero with a distinct code — so a pipeline can branch without parsing text.
  • --timeout <seconds> bounds only your wait, not the run. Defaults to an hour. On expiry the CLI says so and names the dam run get command to pick the result up later — the turn keeps going on the agent.
  • --session <id> continues a session rather than starting one, so a script can hold a thread across several runs.
  • run get prints the recorded reply, --json gives you the raw payload, and -w, --wait blocks until the turn ends. A session that never finished a headless run here — or whose record has since been evicted — reports that rather than an empty answer.

A dropped connection doesn't lose the run. The turn is running on the agent, not in your terminal, so the CLI reconnects with backoff, reloads the session, and finishes from the agent's own record of the run — printing only the text it hasn't already printed. If the agent itself went down mid-run, the run won't finish: the CLI says so and exits non-zero, and you run it again. That's also why a run record lives on the agent: delete the session and the record goes with it, so treat run get as a way to collect a result soon after, not as durable history.

A run never answers an approval for you

If the agent asks permission for a tool call, or reaches a host its network rules don't cover, dam run never decides on your behalf. It prints a line naming what's being asked and the dam approval command that clears it, and waits.

A detached run (--async) has nobody attached to receive that prompt, so the ten-minute orphan window applies — the request expires, that one tool call fails, and the turn carries on. See Sessions. If a run needs approvals, stay attached, or pre-approve what it will reach.

SSH access

dam ssh connect <agent>                # Open an SSH session to an agent
dam ssh connect <agent> -x code        # Launch VS Code Remote-SSH against the agent
dam ssh connect <agent> -x zed         # Launch Zed against the agent
dam ssh connect <agent> -- -L 8080:localhost:8080 -N   # Pass extra arguments to ssh (ssh mode only)
dam ssh configure <agent>              # Write SSH host config for an agent (no launch)
dam ssh configure -a, --all            # Reconcile the active host's agents (prunes every other entry)
dam ssh configure --clear              # Remove all dam-managed SSH host config

-x, --exec <bin[:mode]> selects the client to launch: an executable name or path, optionally suffixed with :ssh, :code, or :zed to force how it's invoked. dam ssh configure writes the same host config without launching a client, and takes exactly one of an agent, --all, or --clear. Because there is a single managed config for all hosts, --all prunes entries for agents on your other servers too — see the SSH guide.

File Operations

dam import <agent> <path...>           # Upload files/folders to the agent workspace
dam file list <agent> [<path>]         # List a workspace directory's immediate children
dam file list <agent> [<path>] -R      # List everything beneath it, recursively
dam file get <agent> <remote-path>     # Download a single file from the agent
dam file put <agent> <local> <remote>  # Upload a single file to the agent

Import bundles local paths into a gzipped tar and uploads them. Each path is merged into work/<basename> on the agent: matching files are overwritten and files already there that aren't in the bundle are kept. A bundled file that would land where a directory exists refuses the whole import. Excluded by basename at every level: node_modules, .venv, __pycache__, .DS_Store. A symlink passed as a <path> argument is rejected and the import fails; symlinks found inside an imported directory are skipped, not followed. Use -y, --yes to skip the confirm (required on non-TTY).

File list shows a directory's immediate children; the path defaults to the workspace root. Files and directories are both listed, with a trailing / marking a directory. Pass -R, --recursive to walk the whole subtree instead — paths come back workspace-relative and sorted, with empty directories included. --json emits each entry as { path, type }, the same either way.

File get/put operate on single files. file get writes to basename(remote-path) in the current directory by default; use -o, --output <path> to choose the local path, --stdout to stream to stdout instead of writing a file, and --overwrite to clobber an existing local file. If -o names an existing directory, the file lands inside it under its remote basename, and --overwrite is ignored with --stdout. file put takes --overwrite to clobber an existing remote file.

Usage metrics

dam metrics <agent>                     # Token spend, runtime, and context usage
dam metrics <agent> --session <id>      # Narrow to one session
dam metrics <agent> --since 168 --json  # Last 7 days, machine-readable
  • --since <hours> is the lookback window (max 720; defaults to all time), --limit <n> caps how many recent calls are included (default 100, max 1000).

Terms of Use

dam terms show                          # Current terms text, version, and your acceptance state
dam terms status                        # Exits non-zero if unaccepted — usable as a CI gate
dam terms accept                        # Interactive on a TTY
dam terms accept --yes                  # Accept without the prompt (required on non-TTY)
dam terms accept --expect-version <v>   # Fail if the server's version differs from the one you reviewed

If a command fails with Terms of Use acceptance required

Run dam terms accept. The CLI prints this hint itself, and --yes clears the gate headlessly so CI never needs a browser. --expect-version is deliberately not called --version, which is reserved for the CLI's own version.

Utility

dam ping             # Reach the configured server and check compatibility
dam version          # Print the local CLI version, the server's, and the latest on npm
dam update           # Update the CLI to the latest stable release (alias: dam upgrade)
dam --version        # Show CLI version
dam --help           # Show help

Agent Addressing

Agents can be referenced by name (case-sensitive, exact match) or by ID — agent- followed by a fixed-length hex string. A agent- prefix alone doesn't make something an ID, so agent-2 is a perfectly good name; a name is refused only when it would be mistaken for an ID outright. If a name matches multiple agents, the CLI exits with an error.

Compatibility

The CLI probes the server's version before each networked command, and there are three outcomes:

  • Current enough — nothing to see.
  • Behind the server, but at or above its advertised minimum — a warning on stderr, and the command proceeds.
  • Below the minimum — networked commands hard-fail with an upgrade prompt. Informational commands still run: dam version reports the same verdict but always exits 0, so you can diagnose the mismatch.

If the server advertises no minimum, the hard-fail never triggers. Run dam update (or npm install -g @dam-agents/cli@latest) to update.