dots workspaces, dots account, and dots providers

The dots workspaces, dots account, and dots providers families, command by command. Every signature, argument, and option below is read from the CLI's own command tree, so this page cannot drift from dots --help. Every other family is listed in CLI Reference.

dots workspaces

dots workspaces [options] [command]

Workspaces: provision additional companies owned by your login identity, read the active company's plan, manage its avatar, and keep the per-user directory registry.

dots workspaces create

dots workspaces create [options]

Provision an additional workspace owned by your identity (workspace.provision-gated); switch into it with --company <slug> or dots use <slug>.

Options:

• --name <name> — Workspace display name (required); the slug is derived from it.

dots workspaces plan

dots workspaces plan [options]

Read the active company's billing plan tier (free | pro | enterprise) — the tier the Settings plan display shows.

dots workspaces avatar

dots workspaces avatar [options] [command]

Set or clear the active workspace's avatar (workspace.settings.manage-gated).

dots workspaces avatar set

dots workspaces avatar set [options]

Upload the active workspace's avatar from a local image file. Raster images only (PNG, JPEG, WebP, GIF) — SVG is refused — capped at 25 MiB, and the response carries a freshly-signed URL. This is a TENANT-WIDE identity change; dots account avatar set is the self-scoped one.

Options:

• --file <path> — Path to the image file to upload.

dots workspaces avatar clear

dots workspaces avatar clear [options]

Clear the active workspace's avatar. The stored object is left as an orphan; only the pointer goes.

Options:

• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Resolve and report what would change; writes nothing.

dots workspaces registry

dots workspaces registry [options] [command]

The per-user workspace registry: the local directories this account has registered, newest-selected first. Distinct from workspaces create, which provisions a COMPANY.

dots workspaces registry list

dots workspaces registry list [options]

List this account's registered directories, newest-selected first (the head is the default cwd). The route answers the whole registry, so --limit/--offset window it here.

Options:

• --limit <n> — Maximum records to return.
• --offset <n> — Records to skip before returning the page.
• --count — Print the number of records this list returns instead of the records themselves.

dots workspaces registry add

dots workspaces registry add [options] <path>

Register a local directory. Idempotent on the (machine, path) key: re-adding one already registered on the same machine returns it with its name preserved and selects it, so there is no duplicate entry to clean up.

Arguments:

• <path> — Absolute path of the directory to register.

Options:

• --name <name> — Display name for the entry (defaults to the path's last segment).
• --machine <id> — The registered machine this path lives on (uuid, from dots machines list). The same path on two machines is two entries; omit it for an entry that names no machine.

dots workspaces registry rename

dots workspaces registry rename [options] <id>

Rename one registry entry. The registered path is unchanged.

Arguments:

• <id> — Registry entry id (uuid), from dots workspaces registry list.

Options:

• --name <name> — New display name (required).

dots workspaces registry select

dots workspaces registry select [options] <id>

Make one registry entry the default cwd. There is no set-default route — selecting touches the entry's last-selected timestamp, and the registry is ordered newest-selected first.

Arguments:

• <id> — Registry entry id (uuid), from dots workspaces registry list.

dots workspaces registry remove

dots workspaces registry remove [options] <id>

Remove one entry from this account's registry. The directory on disk is untouched — only the registration goes.

Arguments:

• <id> — Registry entry id (uuid), from dots workspaces registry list.

Options:

• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Resolve and report what would change; writes nothing.

dots account

dots account [options] [command]

Your own human account — the identity behind this credential.

dots account avatar

dots account avatar [options] [command]

Set or clear your own account avatar.

dots account avatar set

dots account avatar set [options]

Upload your own account avatar from a local image file. Raster images only (PNG, JPEG, WebP, GIF) — SVG is refused — capped at 25 MiB, and the response carries a freshly-signed URL. Self-scoped: the principal written is the one behind this credential, never a named one, and an agent credential is refused (only a human account carries an avatar).

Options:

• --file <path> — Path to the image file to upload.

dots account avatar clear

dots account avatar clear [options]

Clear your own account avatar. The stored object is left as an orphan; only the pointer goes.

Options:

• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Resolve and report what would change; writes nothing.

dots providers

dots providers [options] [command]

Model providers: the local-agent availability snapshot, each provider's model catalog, an on-demand re-probe, and this instance's bring-your-own-key custody.

dots providers list

dots providers list [options]

Render the local-agent provider availability snapshot — per provider: whether it is available, its transport, whether the binary was detected, and its auth status. The route answers the whole snapshot in one read, so --limit/--offset window it here rather than on the request; a composition with no availability probe answers an empty snapshot rather than failing.

Options:

• --limit <n> — Maximum records to return.
• --offset <n> — Records to skip before returning the page.
• --count — Print the number of records this list returns instead of the records themselves.

dots providers models

dots providers models [options] <name>

Read one provider's curated model catalog and its configured default (the composer's Model picker). An instance with no model-list handle wired answers 503; a keyless provider answers 503 naming the provider, never the key.

Arguments:

• <name> — Provider name (claude-code, codex, cursor, openrouter, hermes, openclaw).

dots providers rescan

dots providers rescan [options]

Re-probe the local-agent binaries and re-wire newly detected adapters, answering the freshly probed snapshot. Run it after installing or authenticating a provider CLI. An instance with no re-scan hook wired answers 503.

dots providers keys

dots providers keys [options] [command]

Provider-key custody (workspace.settings.manage-gated). A raw key travels IN only — no read on this surface ever returns a key value.

dots providers keys status

dots providers keys status [options]

Read per-provider key custody and the capability states derived from it: who owns the keys (this instance or its host environment), which secure-storage backend is available, and whether semantic search, AI fill, and Chat are active or degraded. Presence and state only — never a key value.

dots providers keys set

dots providers keys set [options]

Seal a raw provider key for one capability. The key travels in the request body and is never echoed back: the response is the same status projection providers keys status serves. On a hosted or self-host instance whose keys belong to its host environment, the write is refused (503) rather than silently ignored.

Options:

• --capability <name> — Which capability's key to write: embeddings (voyage), ai (anthropic), or chat (openrouter).
• --key <value> — The raw provider key. Prefer --key-file so the value stays out of shell history.
• --key-file <path> — Path to a file whose trimmed UTF-8 content is used as the key instead of --key. Mutually exclusive with --key.

dots providers keys clear

dots providers keys clear [options]

Clear one capability's stored provider key. This is the same PATCH providers keys set drives, sending null for that capability — the other capabilities' keys are untouched. The capability degrades until a key is set again.

Options:

• --yes — Confirm the destructive action (required; it cannot be undone).
• --dry-run — Resolve and report what would change; writes nothing.
• --capability <name> — Which capability's key to clear: embeddings (voyage), ai (anthropic), or chat (openrouter).

generator: apps/docs/pipeline/generate-reference.ts — regenerate with pnpm --filter @dots/docs docs:generate:reference; a hand edit to this page fails the docs drift gate.