Dawn CLI

Dawn CLI is the terminal client for Dawn. Use it when you want the same workspace agents, connected sources, private threads, attachments, and local project context from a shell.

What this page is for

• Use Dawn from a terminal without opening Dawn Web, Desktop, or VS Code.
• Start private Dawn threads against the workspaces and agents your account can already access.
• Give Dawn local workspace context from the directory you run it in, or from an explicit --root path.
• Attach local files and clipboard images to a prompt.
• Send one-off non-interactive prompts from scripts with dawn send.

If you want Dawn inside VS Code, use the VS Code Extension. If you want another AI client to call Dawn over MCP, use MCP and API Credentials.

Install

Dawn CLI is published as a Node package. Install it globally to add the dawn command to your PATH.

Install the CLI globally. Requires Node.js 22 or newer.

npm install -g @amaretto-software-labs/dawn-cli

Confirm the global command is available.

dawn --version

Sign in.

dawn login

Open the terminal UI.

dawn

The package name is @amaretto-software-labs/dawn-cli. The executable command is dawn.

Start commands

Once the dawn command is installed and available on your PATH, these are the normal entry points.

Start interactive Dawn in the current directory.

dawn

Start Dawn with an explicit local workspace root. Shell tools inherit the workspace policy unless you set a local override.

dawn --root ~/work/acme-api

Reduce local shell execution to safe commands for this session.

dawn --root ~/work/acme-api --allow-shell-tools

Inspect the current CLI auth, config, and context.

dawn status

List accessible workspaces without opening the TUI.

dawn workspaces

The default local workspace root is the shell’s current working directory. Use --root when the terminal is somewhere else but Dawn should read/search a specific project.

Top-level command reference

Global options and parameters

Global options can be passed before the command, for example dawn --root ~/repo send "...".

Sign in and sessions

Dawn CLI supports browser sign-in, stored API credentials, and one-process credentials.

# Browser sign-in.
dawn login

# Store a Dawn API credential interactively.
dawn api-credential

# Store a Dawn API credential from stdin.
printf '%s' "$DAWN_API_CREDENTIAL" | dawn api-credential --stdin

# Use an API credential for this process without storing it locally.
DAWN_API_CREDENTIAL="dmcp_..." dawn

# Clear the stored local session.
dawn logout

• DAWN_API_CREDENTIAL takes precedence over any stored browser session or stored API credential.
• Stored sessions are matched to the configured Dawn target, so switching API/identity/auth endpoints can require a separate sign-in.
• Standalone binary builds use native secure storage: macOS Keychain, Windows DPAPI, or Linux Secret Service.
• Node installs and development builds try keytar first, then fall back to native secure storage where available.
• DAWN_CLI_ALLOW_INSECURE_FILE_SESSION=1 opts into plaintext local session storage. Use that only when you explicitly accept the local risk.

Interactive first run

1. Open a terminal in the project directory you want Dawn to understand.
2. Run dawn, or run dawn --root <path> if the project root is elsewhere.
3. If signed out, choose Browser sign-in or API credential.
4. Select the workspace. Dawn prefers the persisted workspace and otherwise selects the first available workspace.
5. Select the agent. Dawn prefers the persisted agent, then the default agent, then the first CLI-enabled agent.
6. Continue the selected thread, choose another thread with /threads, or start fresh with /new.
7. Send a prompt from the composer.

Interactive slash commands

Type / in the composer to see available local commands and Dawn-provided prompt commands for the selected workspace. Signed-out mode only exposes /login, /theme, /help, and /quit.

Keyboard controls

Attachments and generated files

• Type @ to open the local file picker rooted at the CLI workspace root.
• Press Tab or Enter in the file picker to attach the selected file.
• Paste one or more local file paths to attach them when the pasted text is recognized as paths.
• Paste a clipboard image to attach it as an image when your platform and terminal clipboard support it.
• Each uploaded attachment is limited to 25 MB.
• Use Ctrl+Up and Ctrl+Down to select pending attachments.
• Press Delete or Backspace to remove the selected pending attachment.
• Returned files, images, and HTML artifacts are cached under .dawn/downloads inside the CLI root path.

Non-interactive sends

Use dawn send when a script should send exactly one prompt and print the assistant response.

# Send one prompt and print the assistant response.
dawn send "Summarize the release blockers for this workspace."

# Target a workspace and agent by name.
dawn send \
  --workspace "Engineering" \
  --agent "Support Agent" \
  "Summarize CFA-123 and list the next actions."

# Continue a known thread by id.
dawn send \
  --workspace "Engineering" \
  --agent "Support Agent" \
  --thread "thread-id" \
  "Add a concise QA checklist."

# Script-friendly usage with a one-process credential.
DAWN_API_CREDENTIAL="dmcp_..." dawn send \
  --workspace "Engineering" \
  --agent "Release Agent" \
  "Draft a release-risk brief for today's merged PRs."

• --workspace accepts a workspace id or exact workspace name.
• --agent accepts an agent id or exact agent name.
• --thread accepts a thread id and continues that thread.
• If a name is ambiguous, use the id.
• The prompt text is required and is joined from all remaining command arguments.
• The command exits non-zero if auth, workspace selection, agent selection, sending, or response waiting fails.

Local workspace context and tools

Dawn CLI sends local client context with each prompt, including client type, session id, capability ids, and the selected workspace root. Local file tools are scoped to that root path.

# Use the current directory as local context.
cd ~/work/acme-api
dawn

# Use a different root without changing shell directories.
# Shell tools inherit the workspace policy unless you set a local override.
dawn --root ~/work/acme-api

# Reduce local shell execution to safe commands for this session.
dawn --root ~/work/acme-api --allow-shell-tools

# Explicitly allow all shell commands locally, still capped by workspace policy.
dawn --root ~/work/acme-api --allow-unsafe-shell-tools

# Force shell tools off locally even if the workspace allows them.
dawn --disable-shell-tools

• Read/search tools include local context summary, directory listing, file finding, file reads, and content search.
• File write and patch tools are exposed only when the effective shell mode is not disabled.
• Shell commands are refused unless the effective shell mode allows them.
• The workspace policy is the maximum allowed mode. Local client settings can inherit or reduce it, never raise it.
• With no local shell flag, the CLI inherits the workspace policy.
• If the workspace disables shell tools, shell commands are always refused.
• If the workspace allows safe shell tools, only safe shell commands can run, even with --allow-unsafe-shell-tools.
• If the workspace allows all shell tools, all commands can run only when the local mode inherits that policy or uses --allow-unsafe-shell-tools.
• --allow-shell-tools reduces local shell execution to safe commands.
• --disable-shell-tools disables shell commands locally even when the workspace allows them.

Endpoint overrides

Normal published CLI builds include the default Dawn endpoints. Most users should not need to set these flags or variables.

# Override Dawn endpoints.
dawn --api https://api.dawnhq.ai \
  --identity https://identity.dawnhq.ai \
  --auth-app https://app.dawnhq.ai

# Equivalent endpoint overrides.
export DAWN_API_URL="https://api.dawnhq.ai"
export DAWN_IDENTITY_API_URL="https://identity.dawnhq.ai"
export DAWN_AUTH_APP_URL="https://app.dawnhq.ai"
dawn

Troubleshooting

• The CLI opens but I am not signed in: choose a sign-in method from the picker, or run dawn login or dawn api-credential.
• I typed a prompt while signed out: the CLI opens the auth picker instead of sending. Sign in, then send the prompt again.
• No workspaces or agents appear: confirm the same account can see them in Dawn Web and that the selected agent is enabled for CLI/client use.
• My API credential is ignored: check whether DAWN_API_CREDENTIAL is set. Environment credentials take precedence over stored sessions.
• The wrong workspace, agent, thread, or root keeps loading: run dawn status and inspect the persisted context. Switch with /workspaces, /agents, /threads, or restart with --root.
• Shell commands are refused: the effective shell mode does not allow them. The workspace policy is the maximum allowed mode; local settings can inherit or reduce it, never raise it.
• Attachment upload fails: confirm you are signed in, a workspace and agent are selected, the path points to a file, and the file is under 25 MB.
• Browser sign-in cannot open the callback: check local firewall or proxy rules, and use DAWN_REDIRECT_PORT if the default port is unavailable.

Give me a first-use checklist for Dawn CLI in this repository.

List what this selected agent can access from the CLI right now.