Install The CLI

The dots command-line interface ships inside the Dots desktop app: installing the app is how you get the CLI, and there is no separate package to install.

Install The Desktop App

Download and install the Dots desktop app. The packaged app carries the CLI as a single bundle beside its other payloads, at resources/daemon/cli.mjs inside the installation directory. On Windows the installer also writes a dots command onto your account's PATH: a small dots.cmd shim in the app's bin directory that runs the bundled CLI under the Dots executable itself. Because the app supplies the runtime, no separate Node.js installation is required — the installed app is self-contained, carrying its own payloads rather than reading a source tree.

Verify The Install

Open a new terminal so the updated PATH is picked up, then check the version:

dots --version

The output is three lines: the CLI build, the version of the database engine the app bundles, and the schema head that build ships against. A field the CLI cannot resolve prints as unknown rather than as a guess.

Connect The CLI To A Workspace

The CLI reaches a Dots instance through a stored credential. dots auth login records the API base URL and, when you supply one, an API key. It fetches the actor before storing anything, so a login pointed at an unreachable or wrong endpoint fails right there instead of on your next command:

dots auth login --api-key-file ./dots-api-key.txt

dots auth whoami prints the identity and company the API resolves for the current credential, which is how you confirm which instance the CLI is talking to. dots auth logout clears the stored record again. The key itself is a scoped credential you issue with dots access credentials issue.

In a coding-agent session, configure the agent's own identity before other commands:

dots auth login --setup-agent "Coding agent" --company <slug>
dots auth whoami

Setup explicitly assigns Editor to a separate agent principal and stores a credential that expires after 90 days. The human login is preserved. Each workspace has its own agent login. To use an already provisioned agent with narrower grants, import its token with dots auth login --agent --api-key-file <path> --company <slug>. Coding-agent sessions and dots mcp refuse a missing or human agent credential. A human DOTS_API_KEY override must be removed or replaced before the stored agent login can take effect.

A script that makes many calls can resolve its credential once and then call the API directly instead of starting the CLI for every call. dots auth token prints the bearer the invocation resolves, together with the API base URL and the workspace it selected. Inside a coding-agent session that bearer is the workspace's agent credential, verified as an agent before anything prints. The value is a live secret: read it into memory and never echo, log, or store it.

With no credential stored, the CLI addresses the local daemon on this machine at http://127.0.0.1:3687/api/v1, and starts that daemon on demand if the connection is refused. That default reaches only this machine; a stored credential is what points the CLI at a hosted or self-hosted workspace.

Where The Credential Lives

The CLI prefers your operating system's keychain, storing the record under the service name dots-cli. Where no keychain is available it refuses to store the credential rather than silently writing it to disk; setting DOTS_ALLOW_PLAINTEXT_CREDENTIALS=1 explicitly opts into a fallback file at ~/.dots/credentials.json, created owner-only on POSIX systems. Either way the record holds the base URL, the optional API key, and a hint of the identity the login was validated against.

Two environment variables and two flags sit alongside it. --api-url overrides the endpoint for a single invocation, and API_BASE_URL supplies one when no credential is stored; DOTS_API_KEY supplies a bearer token the same way. --company <slug> selects which of your memberships an invocation runs against, and DOTS_COMPANY sets that default from the environment. Below those two sits a per-repository binding — a committed dots.json holding { "company": "<slug>" } at a repository root, written by dots use <slug> --repo — and below that the machine-wide default dots use <slug> records.

What The CLI Can Do

The dots CLI's workspace families are a one-to-one front-end onto the platform: they read and write rows, edges, and Dotabases, run search, drive Chat, manage access, and launch the MCP server that hands the same data to an agent. Command families span that surface — dots rows, dots edges, dots search, dots views, dots chat, dots access, and dots mcp among them. dots local separately controls the machine-local daemon without calling the platform API.

Every command shares one set of global options. --format chooses the renderer, and it defaults to md on every surface rather than switching on whether output is piped; json, yaml, table, csv, and plain are the opt-in alternatives for scripting. A script can instead set DOTS_SCRIPT=1, which makes json the default and turns the agent marker off; an explicit --format or --agent-mode still wins. --level sets how much of each record the Markdown envelope carries: scan is identity alone, summary adds the bounded fields, and full is the widest record. The survey reads — the list and search commands of the knowledge-bearing families, plus dots memory recall — default to summary, so a listing stays cheap until you ask for more, and --level full restores the widest record wherever that default narrowed one. Three more flags trim the result: --fields projects an exact allowlist and switches tiering off, --depth expands one hop of edges, and --token-budget caps the output at a record boundary. CLI Reference lists the full command surface. Connect Your Agent covers pointing an AI assistant at your Dotabases over MCP.