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¶
Requires Node 20 or later.
Configuration¶
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 exceptdam auth statusand thedam auth tokensubcommands, 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 onauth login,auth logout,auth status,auth token revoke,ping,dam ssh,chat,file get,file put,config set,agent create-interactive,satellite mcp, orsatellite shell. (file listdoes 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--scopeand you getagents:operatealone; a key always carries at least one scope. The valid values areagents:read,agents:operate,agents:manage,credentials:read, andcredentials:manage.--agentdefaults 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 asDAM_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
createflags:--template <id>(defaults to the install's default template),--provider <id-or-name>(defaults to your preferred provider — the onedam connection list --providersmarkspreferred),--description <text>,--env KEY=VAL(repeatable),--wait,--timeout <seconds>(default 120),--json.--providernames a model-provider connection, by connection id or by a name unique among your providers —dam connection listshows both. An unknown, ambiguous, non-provider or inactive--provideris refused before the agent is created, so a wrong flag costs nothing. Resolving a name reads your connections, which needscredentials:read; pass a connection id to create withagents:managealone.dam agent create-interactivecollects the provider for you and needs neither flag.- The harness is picked per session, so
createdoesn't take one.updatesets the agent's defaults:--harness,--model(named the waydam agent modelslists them),--setting id=value(repeatable), and--kind chat|channel|scheduledto say which default you're setting (defaultchat). 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
disabledinlistandget, and nothing — a schedule, a message, a session — wakes it untildam agent enable. --waitis available oncreateandrestart; pair with--timeoutto change the 120s default.--jsononlist,get,delete, andrestartfor machine-readable output.
Templates¶
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)
mcpandshellstay 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),--descriptionand--max-concurrent. Without--name, the satellite is named after the server or command it offers, oruser@hostname.mcpstarts the server you name after--, or forwards to one already listening with--url. A barehost:portmeanshttp://host:port/mcp.--header "Name: value"(repeatable) is sent to a--urlserver, and--cwdsets 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.-
shelltakes 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.--cwdand--timeoutset 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: -
No agent can call a satellite's tools until you grant it the satellite.
grantandrevoketake any of your agents by name or ID. cancelonly asks: a command that's already running may still finish.rmdoesn't stop commands already running on the machine. The runningdam satellitestops taking new work, and you can start it again to register it anew. It confirms on a TTY; pass--yesnon-interactively.listandjobstake--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 addalso 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/skillsbecomesacme/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--pathas 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 removeconfirms on a TTY — pass-y, --yesnon-interactively.catalog --agent <ref>annotates each skill as not-installed / installed / update-available and scans private sources through that agent's pod.installinstalls the version the source was last scanned at, not whatever its repo holds this second — there is no--versionflag and no separateupdateverb; re-runninginstallupdates in place. To pick up a commit pushed in the last few minutes, runsource refresh <id>first so the next scan re-reads upstream.publishworks only on standalone (locally-authored) skills, and only against GitHub sources. Its--sourceis the repo to open the pull request against — not where the skill came from, as it means oninstall/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.
disconnecttakes--channel-idto say which binding to release; it is required once the agent has more than one connected, and optional when it has just one.disconnectis 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.
--ambientstarts 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
connectfor 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 bindis stricter: it refuses an agent already connected to that conversation rather than updating it. - There's no
defaultsubcommand. Which agent unnamed mentions reach is set in-chat with/dam default <agent>. dam channel listprintsTYPE,IDENTIFIER, andAMBIENT. 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 deleteall require. Run/dam loginonce 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
listflags:--status pending|resolved|expired|all(defaultpending),--limit <n>(1–500).--onceand--entire-hostare mutually exclusive.- The web UI offers the same choices in Activity under different names: bare
approveis Allow permanently,--onceis Allow once,--entire-hostis Allow all of <host>,deny --onceis Deny this request, and baredenyis 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.
--onceand--entire-hostare 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/--everyto specific days, e.g.MO,WE,FR. Can't combine with--rrule, whose body carries its ownBYDAY. Onupdateit only applies while you're rebuilding the recurrence, so pass it together with--dailyor--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 tofreshoncreate; onupdate, 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.updatealso takes--precheck-noneto 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, --promptand--prompt-file— passing both, or neither, is an error. A promptlessdam runrefuses rather than waiting on stdin, so it can't hang a script by accident. - The answer goes to stdout; progress, warnings, and the closing
stopReasongo to stderr, so redirecting stdout gives you just the reply. - Exit codes carry the outcome.
0means 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 thedam run getcommand 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 getprints the recorded reply,--jsongives you the raw payload, and-w, --waitblocks 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 versionreports 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.