A lot of work starts in a terminal. You are inspecting a checkout, looking at a branch that has not been pushed yet, tailing a log file, or piecing together a quick script for a release. Until now, getting a Dawn agent involved in any of that meant leaving the terminal — opening Dawn Web, jumping into the VS Code extension, or pasting a snippet into a channel.
Dawn CLI puts those agents directly in the terminal. The same workspace agents you use everywhere else now run from the shell, with access to the local files in your working directory and a script-friendly mode for automation.
npm install -g @amaretto-software-labs/dawn-cli
dawn login
dawnThe package requires Node.js 22 or newer. The installed command is simply dawn.
The Same Threads, From Your Shell
Running dawn opens an interactive terminal UI. You sign in, pick a workspace, pick an agent, and continue a private CLI thread. A thread started in the terminal is a real Dawn thread — it uses the same workspace, the same agent instructions, the same connected sources, and the same conversation history that thread has anywhere else. The only thing the CLI adds on top is the local context of the directory you ran it from.
That keeps the mental model simple. Workspaces still decide which sources and policies are available. Agents still decide what context, skills, integrations, and commands they can use. Attachments and generated files still stay attached to the conversation. The terminal is just another way in.
Your Workspace Knowledge Comes With You
Working from a terminal does not mean working with a stripped-down agent. Everything the agent already has access to elsewhere — connected integrations, memory pages, skills, scheduled tasks, prior conversation history — is available the same way from the CLI. Ask about a Jira ticket and the agent reads it. Ask for the team runbook and it pulls the matching Confluence or Notion page. Ask what the design lead posted to the project channel this morning and the agent answers from whichever integration has access.
The local root is additive, not a replacement. The full workspace knowledge the agent already had is still there, and the files on the machine in front of you sit alongside it in the same prompt. Ask the agent to compare a local branch against the spec in Notion, or to draft a release note that ties the diff in this checkout to the Jira tickets it closes, and it pulls from both worlds at once.
Your Working Directory Is the Context
By default, Dawn CLI uses the current working directory as its local root. You can also point it somewhere explicit:
dawn --root ~/work/acme-apiWhen a local root is available, the agent can describe the environment, list and find files inside the root, read their contents, and search across them. That matters because the most interesting state on a developer’s machine is often the state that does not exist anywhere else: unpushed commits, uncommitted experiments, generated files, build output, or a branch that GitHub, Azure DevOps, GitLab, and Bitbucket have never seen. Connected sources cannot reach any of that. The CLI lets the agent work from what is actually on disk.
Local file access is scoped to the selected root. If you opened Dawn in the wrong directory, exit and run it again with --root pointing at the right one.
Attaching Files Without Leaving the Terminal
Most attachment workflows in a terminal feel awkward. Dawn CLI tries to make the common ones natural. Type @ to browse files under the local root and pick one. Paste a local file path and Dawn attaches the matching file. Paste a clipboard image, when your terminal and platform clipboard support it, and Dawn attaches it as an image. If you grabbed the wrong file, remove it from the pending attachments before sending.
Anything the agent generates — files, images, HTML artifacts — is saved under .dawn/downloads inside the CLI root, so the outputs land in the same working tree you are already using. Open them, commit them, throw them away. They are local files.
In practice this covers most of the things you actually want to do from a terminal: ask the agent to inspect a log file from disk, attach a screenshot you just copied from another app, generate an HTML prototype and open the saved file, or get a code review on local changes before you push them.
Sending Prompts From Scripts
The CLI is not only an interactive app. It also has a script-friendly path for cases where you want a Dawn answer back on stdout without opening any UI:
dawn send "Summarize the release blockers for this workspace."You can target a specific workspace, agent, and thread:
dawn send \
--workspace "Engineering" \
--agent "Release Agent" \
--thread "thread-id" \
"Draft a release-risk brief for today's merged PRs."dawn send waits for the assistant response, prints it, and exits non-zero when authentication, selection, sending, or response waiting fails. That makes it usable from release scripts, local automations, or CI checks where you want the failure to surface like any other command.
Signing In Three Different Ways
Browser sign-in works the way you would expect:
dawn loginWhen a browser flow is not the right fit — running on a remote server, inside a container, or from a CI step — the CLI accepts API credentials directly:
dawn api-credential
printf '%s' "$DAWN_API_CREDENTIAL" | dawn api-credential --stdinFor one-off use where you do not want to store anything locally, set the credential as an environment variable for a single command:
DAWN_API_CREDENTIAL="dmcp_..." dawn send "List my open release tasks."Stored sessions are bound to the configured Dawn target. Switching from one API or identity endpoint to another will not silently reuse a token issued for the previous target — you will be asked to sign in again.
Credential storage is secure by default. On install, the CLI tries keytar first and falls back to the native OS credential store where available. Plaintext local session storage is only used if you explicitly opt into it for development.
Shell Access That Respects Workspace Policy
The CLI can let an agent run shell commands on your machine, but never beyond what the workspace policy allows. The workspace mode is the maximum; local CLI flags can inherit or reduce it, never raise it.
In practice that means a few clear outcomes. If the workspace has shell tools disabled, no command runs. If the workspace allows safe shell tools, destructive commands are still refused. If the workspace allows all shell tools, the CLI runs them only when the local mode inherits or explicitly opts into unsafe shell tools. And whatever the workspace allows, you can always force shell tools off locally with --disable-shell-tools.
The flags map directly onto those modes:
# Inherit the workspace policy.
dawn
# Reduce local shell execution to safe commands.
dawn --allow-shell-tools
# Allow all locally, still capped by workspace policy.
dawn --allow-unsafe-shell-tools
# Force shell tools off locally.
dawn --disable-shell-toolsThis is the same direction the VS Code extension already takes. Local surfaces can expose useful machine context, but workspace policy stays the ceiling.
Slash Commands and Status Checks
Inside the terminal UI, type / to see the available local commands and Dawn workspace Prompt Commands. The local set covers the things you want close at hand: signing in, switching workspace, switching agent, switching thread, starting a new thread, renaming a thread, changing theme, and quitting.
Outside the UI, dawn status prints the current authentication summary, persisted context, and resolved configuration as JSON. It is the fastest way to confirm which endpoint, workspace, agent, thread, and root path the CLI will use before you run anything.
dawn statusHow This Relates to MCP
The CLI is not the same thing as Dawn over MCP in Codex, Cursor, and GitHub Copilot. The two are inverses of each other.
MCP lets another tool call Dawn as a server. Codex, Cursor, and Copilot stay the user-facing surface, and Dawn is reached through their UI as a set of tools and prompts the host application can use. Dawn CLI is the other direction — Dawn itself is the surface, and your terminal is the input. You talk to a Dawn agent directly, the agent uses Dawn’s connected sources and skills, and the conversation belongs to Dawn rather than to the host editor.
Both can run on the same machine without conflict. Use MCP when the work belongs in another tool that you want to make smarter with Dawn. Use the CLI when you want to talk to Dawn from the shell, with the full Dawn UI and the full Dawn workspace context behind it.
Where the CLI Fits Alongside Everything Else
Dawn CLI is not replacing the surfaces Dawn already runs in. Dawn Web still handles full workspace management and review. The VS Code extension is still the right surface when the editor is the centre of the work. Slack, Discord, Telegram, Teams, and the web widget still handle channel-based conversation.
The CLI fits the work that starts in a terminal. Local context, scriptability, and fast command-line access matter most there. Dawn now runs there directly.
Getting Started
The setup guide and full command reference are in the docs: