CLI

Dropstone CLI options and commands.

The Dropstone CLI by default starts an interactive session when run without any arguments.

dropstone

But it also accepts commands as documented on this page. This allows you to interact with Dropstone programmatically.

dropstone run "Explain how closures work in JavaScript"

tui

Start an interactive Dropstone session. This is the default when you run dropstone with no subcommand; dropstone tui is the explicit form.

dropstone [project]

Flags

Flag	Short	Description
	`-c`	Continue the last session
	`-s`	Session ID to continue
		Fork the session when continuing (use with `--continue` or `--session`)
		Prompt to use
	`-m`	Model to use (`dropstone/dropstone-fast`, `dropstone/dropstone-pro`, or `dropstone/dropstone-heavy`)
		Agent to use
		Port to listen on
		Hostname to listen on
		Enable mDNS discovery
		Custom mDNS domain name
		Additional browser origin(s) to allow CORS

Commands

The Dropstone CLI also has the following commands.

agent

Manage agents for Dropstone.

dropstone agent [command]

create

Create a new agent with custom configuration.

dropstone agent create

This command will guide you through creating a new agent with a custom system prompt and permission configuration. Anything you don't allow is denied in the generated agent's frontmatter.

Flags

Flag	Short	Description
		Directory to write the agent file to (defaults to global or `.dropstone/agent` based on the prompt)
		What the agent should do
		Agent mode: `all`, `primary`, or `subagent`
		Comma-separated list of permissions to allow (default: all). Available: `bash`, `read`, `edit`, `glob`, `grep`, `webfetch`, `task`, `todowrite`, `websearch`, `lsp`, `skill`. Anything omitted is denied. Alias: `--tools`
	`-m`	Model to use (`dropstone/dropstone-fast`, `dropstone/dropstone-pro`, or `dropstone/dropstone-heavy`)

Passing all of --path, --description, --mode, and --permissions runs the command non-interactively.

list

List all available agents.

dropstone agent list

attach

Attach a terminal to an already running Dropstone backend server started via serve or web commands.

dropstone attach [url]

This lets you point an interactive session at a Dropstone server running on another machine. For example:

# On the host machine, start the server
dropstone web --port 4096 --hostname 0.0.0.0

# On another machine, attach a session to it
dropstone attach http://10.20.30.40:4096

Flags

Flag	Short	Description
		Working directory to start the session in
	`-c`	Continue the last session
	`-s`	Session ID to continue
		Fork the session when continuing (use with `--continue` or `--session`)
	`-p`	Basic auth password (defaults to `DROPSTONE_SERVER_PASSWORD`)
	`-u`	Basic auth username (defaults to `DROPSTONE_SERVER_USERNAME` or `dropstone`)

auth

Command to manage credentials and login for providers.

dropstone auth [command]

Use dropstone auth login to sign in to Dropstone. Your credentials are stored at ~/.local/share/dropstone/auth.json.

dropstone auth login

Dropstone reads credentials from this file on every launch.

Flags

Flag	Short	Description
	`-p`	Provider ID or name to log in to
	`-m`	Login method label to use, skipping method selection

list

Lists all the authenticated providers as stored in the credentials file.

dropstone auth list

Or the short version.

dropstone auth ls

logout

Logs you out of a provider by clearing it from the credentials file.

dropstone auth logout

github

Manage the GitHub agent for repository automation.

dropstone github [command]

install

Install the GitHub agent in your repository.

dropstone github install

This sets up the necessary GitHub Actions workflow and guides you through the configuration process. Learn more.

run

Run the GitHub agent. This is typically used in GitHub Actions.

dropstone github run

Flags

Flag	Description
	GitHub mock event to run the agent for
	GitHub personal access token

mcp

Manage Model Context Protocol servers.

dropstone mcp [command]

add

Add an MCP server to your configuration.

dropstone mcp add

This command will guide you through adding either a local or remote MCP server.

list

List all configured MCP servers and their connection status.

dropstone mcp list

Or use the short version.

dropstone mcp ls

auth

Authenticate with an OAuth-enabled MCP server.

dropstone mcp auth [name]

If you don't provide a server name, you'll be prompted to select from available OAuth-capable servers.

You can also list OAuth-capable servers and their authentication status.

dropstone mcp auth list

Or use the short version.

dropstone mcp auth ls

logout

Remove OAuth credentials for an MCP server.

dropstone mcp logout [name]

debug

Debug OAuth connection issues for an MCP server.

dropstone mcp debug <name>

models

List the Dropstone model tiers available to your account.

dropstone models

Output is in dropstone/<tier> format. Dropstone ships three tiers:

Model ID	Tier	Best for
`dropstone/dropstone-fast`	Fast	Default daily-driver. Quick edits, scaffolding, conversational debugging.
`dropstone/dropstone-pro`	Pro	Multi-file refactors, cross-cutting changes, broader reasoning.
`dropstone/dropstone-heavy`	Heavy	Architecture decisions, large migrations, hard debugging.

See Models for the full breakdown and how to set a default.

Flags

Flag	Description
	Refresh the cached model list
	Include metadata (context window, capabilities)

run

Run dropstone in non-interactive mode by passing a prompt directly.

dropstone run [message..]

This is useful for scripting, automation, or when you want a quick answer without opening an interactive session. For example:

dropstone run Explain the use of context in Go

You can also attach to a running dropstone serve instance to avoid MCP server cold boot times on every run:

# Start a headless server in one terminal
dropstone serve

# In another terminal, run commands that attach to it
dropstone run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flags

Flag	Short	Description
		The command to run, use message for args
	`-c`	Continue the last session
	`-s`	Session ID to continue
		Fork the session when continuing (use with `--continue` or `--session`)
		Share the session
	`-m`	Model to use (`dropstone/dropstone-fast`, `dropstone/dropstone-pro`, or `dropstone/dropstone-heavy`)
		Agent to use
	`-f`	File(s) to attach to message
		Format: default (formatted) or json (raw JSON events)
		Title for the session (uses truncated prompt if no value provided)
		Attach to a running dropstone server (e.g., http://localhost:4096)
	`-p`	Basic auth password (defaults to `DROPSTONE_SERVER_PASSWORD`)
	`-u`	Basic auth username (defaults to `DROPSTONE_SERVER_USERNAME` or `dropstone`)
		Directory to run in, or path on the remote server when attaching
		Port for the local server (defaults to random port)
		Model variant (provider-specific reasoning effort)
		Show thinking blocks
		Auto-approve permissions that are not explicitly denied (dangerous!)

serve

Start a headless Dropstone server for API access. Check out the server docs for the full HTTP interface.

dropstone serve

This starts a headless HTTP server that provides programmatic access to Dropstone, without opening an interactive session. Set DROPSTONE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to dropstone).

Flags

Flag	Description
	Port to listen on
	Hostname to listen on
	Enable mDNS discovery
	Custom mDNS domain name
	Additional browser origin(s) to allow CORS

session

Manage Dropstone sessions.

dropstone session [command]

list

List all Dropstone sessions.

dropstone session list

Flags

Flag	Short	Description
	`-n`	Limit to N most recent sessions
		Output format: table or json (table)

delete

Delete an Dropstone session.

dropstone session delete <sessionID>

stats

Show token usage and cost statistics for your Dropstone sessions.

dropstone stats

Flags

Flag	Description
	Show stats for the last N days (all time)
	Number of tools to show (all)
	Show model usage breakdown (hidden by default). Pass a number to show top N
	Filter by project (all projects, empty string: current project)

export

Export session data as JSON.

dropstone export [sessionID]

If you don't provide a session ID, you'll be prompted to select from available sessions.

Flags

Flag	Description
	Redact sensitive transcript/file data

import

Import session data from a JSON file or Dropstone share URL.

dropstone import <file>

You can import from a local file or an Dropstone share URL.

dropstone import session.json
dropstone import https://dropstone.io/s/abc123

web

Start a headless Dropstone server with a web interface.

dropstone web

This starts an HTTP server and opens a web browser to access Dropstone through a web interface. Set DROPSTONE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to dropstone).

Flags

Flag	Description
	Port to listen on
	Hostname to listen on
	Enable mDNS discovery
	Custom mDNS domain name
	Additional browser origin(s) to allow CORS

acp

Start an ACP (Agent Client Protocol) server.

dropstone acp

This command starts an ACP server that communicates via stdin/stdout using nd-JSON.

Flags

Flag	Description
	Working directory
	Port to listen on
	Hostname to listen on
	Enable mDNS discovery
	Custom mDNS domain name
	Additional browser origin(s) to allow CORS

plugin

Install a plugin and update your config.

dropstone plugin <module>

Or use the alias.

dropstone plug <module>

Flags

Flag	Short	Description
	`-g`	Install in global config
	`-f`	Replace existing plugin version

pr

Fetch and checkout a GitHub PR branch, then run Dropstone.

dropstone pr <number>

db

Database tools.

dropstone db [query]

Flags

Flag	Description
	Output format: `json` or `tsv`

path

Print the database path.

dropstone db path

debug

Debugging and troubleshooting tools.

dropstone debug [command]

uninstall

Uninstall Dropstone and remove all related files.

dropstone uninstall

Flags

Flag	Short	Description
	`-c`	Keep configuration files
	`-d`	Keep session data and snapshots
		Show what would be removed without removing
	`-f`	Skip confirmation prompts

upgrade

Updates Dropstone CLI to the latest version or a specific version. dropstone update is an alias and behaves identically.

dropstone upgrade [target]
# or
dropstone update [target]

To upgrade to the latest version:

dropstone upgrade

To install a specific version:

dropstone upgrade 1.0.5

On Windows, if Dropstone is currently running, the installer stages the new build as dropstone.exe.pending. The new version activates automatically on the next launch: no manual file moves required.

Flags

Flag	Short	Description
	`-m`	The installation method to use: `curl`, `npm`, `pnpm`, `bun`, `brew`, `scoop`, `choco`

Global Flags

The dropstone CLI takes the following global flags.

Flag	Short	Description
	`-h`	Display help
	`-v`	Print version number
		Print logs to stderr
		Log level (DEBUG, INFO, WARN, ERROR)
		Run without external plugins

Environment variables

Dropstone reads the following environment variables on launch. These are the supported user-facing variables; anything not listed here is internal and may change or be removed without notice.

Variable	Type	Description
`DROPSTONE_API_KEY`	string	Dropstone API key for headless / CI use (skips browser sign-in)
`DROPSTONE_CONFIG`	string	Path to a `dropstone.json` config file
`DROPSTONE_TUI_CONFIG`	string	Path to a session config file (`tui.json`)
`DROPSTONE_DISABLE_AUTOUPDATE`	boolean	Disable automatic CLI update checks
`DROPSTONE_GIT_BASH_PATH`	string	Path to Git Bash on Windows (used as the shell tool)
`DROPSTONE_SERVER_PASSWORD`	string	Enable HTTP basic auth on `dropstone serve` / `dropstone web`
`DROPSTONE_SERVER_USERNAME`	string	Override the basic auth username (default `dropstone`)

Core concepts

Interactive session

CLI

tui

Flags

Commands

agent

create

Flags

list

attach

Flags

auth

login

Flags

list

logout

github

install

run

Flags

mcp

add

list

auth

logout

debug

models

Flags

run

Flags

serve

Flags

session

list

Flags

delete

stats

Flags

export

Flags

import

web

Flags

acp

Flags

plugin

Flags

pr

db

Flags

path

debug

uninstall

Flags

upgrade

Flags

Global Flags

Environment variables

On this page