> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotbot.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# dotbot CLI commands and flags reference

> Complete reference for every dotbot CLI command, including init, run, workflow, tasks, registry, install, serve, studio, doctor, and more - with flags and usage examples.

dotbot is controlled entirely from the terminal. Every command operates on the current working directory, which must contain (or will receive) a `.bot/` directory. The commands below cover project initialisation, workflow lifecycle, task management, the HTTP runtime, health monitoring, content management, and registry integration.

## dotbot help

Prints the full command list with short descriptions.

```powershell theme={null}
dotbot help
```

***

## dotbot init

Initialises dotbot in the current project by creating `.bot/workspace/` (tracked in git) and `.bot/.gitignore`. Framework files are not copied - the runtime resolves them from `$env:DOTBOT_HOME` at runtime. Safe to run on an existing project; workspace data is never overwritten.

```powershell theme={null}
dotbot init
dotbot init --force
dotbot init --workflow start-from-jira
dotbot init --stack dotnet-blazor,dotnet-ef
dotbot init --workflow start-from-jira --stack dotnet-blazor
dotbot init --copy-runtime
dotbot init --dry-run
```

<ParamField path="--workflow" type="string">
  Workflow identifier to activate. Recorded in `.bot/.control/settings.json`. If the workflow ships project-tier overrides or comes from a registry, its effective content is materialised under `.bot/content/workflows/<name>/`. Use a registry-qualified name (`registry-alias:workflow-name`) for registry workflows.
</ParamField>

<ParamField path="--stack" type="string">
  Comma-separated list of stack identifiers to activate (e.g. `dotnet-blazor,dotnet-ef`). Stacks are applied in dependency order - `dotnet-blazor` automatically includes `dotnet` if it declares `extends: dotnet`. Settings deep-merge in apply order: default, then workflow, then stacks.
</ParamField>

<ParamField path="--force" type="switch">
  Refreshes workflow and stack selections in `.bot/.control/settings.json` and rewrites `.bot/.gitignore`. Workspace data under `.bot/workspace/` is never touched.
</ParamField>

<ParamField path="--copy-runtime" type="switch">
  Copies the full dotbot runtime into `.bot/runtime/` so commands inside the project prefer that copy over the shared `$env:DOTBOT_HOME`. Re-run with `--force` to refresh an existing project-local copy.
</ParamField>

<ParamField path="--dry-run" type="switch">
  Previews what would be created without writing any files.
</ParamField>

***

## dotbot list

Lists all available built-in workflows and stacks, plus any content from installed registries.

```powershell theme={null}
dotbot list
```

***

## dotbot go

Launches the project runtime and the dashboard UI together. If the runtime is already running, attaches to the existing instance rather than starting a second one. The default dashboard port is 8686; the server picks the next available port if 8686 is busy.

```powershell theme={null}
dotbot go
dotbot go --port 9090
dotbot go --open
dotbot go --no-runtime
```

<ParamField path="--port" type="int">
  Preferred port for the dashboard UI. Overrides the default auto-selection.
</ParamField>

<ParamField path="--open" type="switch">
  Opens the dashboard in the default browser after the server starts.
</ParamField>

<ParamField path="--no-runtime" type="switch">
  Starts the UI server without also starting the HTTP runtime.
</ParamField>

***

## dotbot run

Runs or reruns a named workflow that is installed in the project. Equivalent to `dotbot workflow run`.

```powershell theme={null}
dotbot run start-from-jira
dotbot run start-from-prompt --watch
dotbot run start-from-prompt --no-auto-runtime
dotbot run start-from-prompt --poll-interval-ms 2000
```

<ParamField path="<workflow>" type="string" required>
  Name of the installed workflow to run. Use `dotbot workflow list` to see all installed workflow names.
</ParamField>

<ParamField path="--watch" type="switch">
  Keeps the process attached and streams progress output until the workflow completes or is stopped.
</ParamField>

<ParamField path="--no-auto-runtime" type="switch">
  Does not automatically start the HTTP runtime before running the workflow.
</ParamField>

<ParamField path="--poll-interval-ms" type="int">
  Interval in milliseconds between status polls in watch mode. Defaults to 1000.
</ParamField>

***

## dotbot workflow run

Runs or reruns a named workflow. Identical to `dotbot run` - both invoke the same underlying script.

```powershell theme={null}
dotbot workflow run start-from-jira
dotbot workflow run start-from-prompt --watch
```

***

## dotbot workflow add

Adds a new workflow to a project that was already initialised with `dotbot init`. Useful when a team wants to layer additional pipelines on top of an existing installation.

```powershell theme={null}
dotbot workflow add start-from-jira
dotbot workflow add myorg:release-pipeline
```

<ParamField path="<name>" type="string" required>
  Workflow name, either a built-in name or a registry-qualified name in the form `registry-alias:workflow-name`.
</ParamField>

***

## dotbot workflow remove

Removes an installed workflow from the project. Removes the workflow's materialised directory from `.bot/content/workflows/` but does not delete workspace data.

```powershell theme={null}
dotbot workflow remove start-from-jira
```

<ParamField path="<name>" type="string" required>
  Name of the installed workflow to remove.
</ParamField>

***

## dotbot workflow list

Lists all workflows currently installed in the project.

```powershell theme={null}
dotbot workflow list
```

***

## dotbot tasks run

Starts a workflow-agnostic task runner that drains all pending tasks in `.bot/workspace/tasks/standalone/todo/` regardless of which workflow created them.

```powershell theme={null}
dotbot tasks run
```

***

## dotbot tasks stop

Signals the workflow-agnostic task runner to stop after the current task completes.

```powershell theme={null}
dotbot tasks stop
```

***

## dotbot resume

<Warning>
  `dotbot resume` is declared but not yet implemented. Running it prints a message directing you to use `dotbot run <workflow-name>` instead.
</Warning>

***

## dotbot serve

Starts only the per-project HTTP runtime in the foreground, without the dashboard UI. Useful for diagnostics, non-interactive shells, and fleet mode where a wrapper manages the process.

```powershell theme={null}
dotbot serve
dotbot serve --mothership https://dashboard.example.com
dotbot serve --mothership https://dashboard.example.com --mothership-key <key>
```

<ParamField path="--mothership" type="string">
  URL of a mothership dashboard to register with on startup. Used in fleet mode to report this runtime's endpoint to a central dashboard.
</ParamField>

<ParamField path="--mothership-key" type="string">
  API key for authenticating with the mothership dashboard.
</ParamField>

<Note>
  Press Ctrl+C to stop the runtime. On exit it removes `.bot/.control/runtime.json` so the next start gets a fresh connection file.
</Note>

***

## dotbot runtime-status

Shows the current state of the per-project HTTP runtime: PID, URL, start timestamp, and a list of active workflow runs.

```powershell theme={null}
dotbot runtime-status
```

Exit codes: `0` if the runtime is alive and reachable, `1` if it is not running or the recorded PID is stale, `2` if the PID is alive but the HTTP endpoint is unreachable.

***

## dotbot status

Reports the current dotbot installation: version, project initialisation state, active workflow and stacks, and registered registries.

```powershell theme={null}
dotbot status
```

***

## dotbot prune-branches

Deletes stale `workflow/*` and `task/*` git branches older than a given age. Never deletes the currently checked-out branch on any worktree. By default skips branches that have a remote-tracking counterpart.

```powershell theme={null}
dotbot prune-branches
dotbot prune-branches --older-than 14d
dotbot prune-branches --match task --dry-run
dotbot prune-branches --include-remote --force
```

<ParamField path="--older-than" type="string">
  Age threshold for candidate branches. Accepts values like `30d`, `7d`, `2w`. Defaults to `30d`.
</ParamField>

<ParamField path="--match" type="string">
  Which branch prefix to consider: `workflow`, `task`, or `all`. Defaults to `all`.
</ParamField>

<ParamField path="--dry-run" type="switch">
  Prints candidate branches without deleting them.
</ParamField>

<ParamField path="--include-remote" type="switch">
  Includes branches that have a remote-tracking counterpart (`origin/<name>`). Excluded by default.
</ParamField>

<ParamField path="--force" type="switch">
  Skips the confirmation prompt.
</ParamField>

***

## dotbot studio

Launches the visual configuration studio. The studio is a separate UI for browsing and editing dotbot project settings, workflows, and stacks without editing files directly.

```powershell theme={null}
dotbot studio
```

<Note>
  If the studio is already running it opens a browser tab to the existing instance rather than starting a second server. Run `dotbot update` first if the studio is not installed.
</Note>

***

## dotbot doctor

Runs project health diagnostics. Scans for stale worktree locks, orphaned git worktrees, settings integrity violations, missing CLI dependencies, and task queue health issues.

```powershell theme={null}
dotbot doctor
```

<Note>
  Run `dotbot doctor` after a crash or unexpected stop to identify stale locks before retrying a workflow.
</Note>

***

## dotbot install runtime

Copies the dotbot runtime into `.bot/runtime/` in an existing project. Use this to give the project its own pinned runtime copy without re-running `dotbot init`.

```powershell theme={null}
dotbot install runtime
dotbot install runtime --from /path/to/other-dotbot-checkout
```

<ParamField path="--from" type="string">
  Path to an alternative dotbot checkout to copy from. Defaults to `$env:DOTBOT_HOME`.
</ParamField>

***

## dotbot install agent | prompt | skill

Installs a single agent, prompt, or skill into the project. Content can come from the built-in library, a registry, a local path, or a GitHub URL.

```powershell theme={null}
dotbot install skill write-unit-tests
dotbot install agent implementer --version v2
dotbot install skill --from github.com/myorg/dotbot-extras/skills/code-review:v1
dotbot install skill write-unit-tests --global
```

<ParamField path="<type>" type="string" required>
  Content type to install: `agent`, `prompt`, or `skill`. Plural forms (`agents`, `prompts`, `skills`) are also accepted.
</ParamField>

<ParamField path="<name>" type="string">
  Name, local path, registry path, or GitHub URL of the content to install.
</ParamField>

<ParamField path="--from" type="string">
  Fully-qualified source URL including an optional version tag (e.g. `github.com/owner/repo/skills/name:v2`).
</ParamField>

<ParamField path="--version" type="string">
  Version tag to install when the source provides versioned releases.
</ParamField>

<ParamField path="--global" type="switch">
  Installs into `$env:DOTBOT_HOME` rather than the current project. Makes the content available to all projects on this machine.
</ParamField>

<ParamField path="--force" type="switch">
  Overwrites an existing installation at the target location.
</ParamField>

***

## dotbot registry add

Links an enterprise extension registry so that its workflows, stacks, tools, and skills become available via `dotbot init` and `dotbot workflow add`. Registries are git repositories (GitHub, Azure DevOps, GitLab) or local paths containing a `registry.yaml` manifest. Version compatibility and authentication failures are validated at add time.

```powershell theme={null}
dotbot registry add myorg https://github.com/myorg/dotbot-extensions.git
dotbot registry add myorg C:\repos\myorg-dotbot-extensions
dotbot registry add myorg https://github.com/myorg/ext.git --branch release
```

<ParamField path="<name>" type="string" required>
  Short alias used to reference the registry (e.g. `myorg`). Qualify workflow names with this alias when installing: `myorg:custom-workflow`.
</ParamField>

<ParamField path="<source>" type="string" required>
  Git URL or local filesystem path to the registry root. The directory must contain a `registry.yaml` manifest.
</ParamField>

<ParamField path="--branch" type="string">
  Git branch to track. Defaults to the remote's default branch.
</ParamField>

<ParamField path="--force" type="switch">
  Overwrites an existing registry registration with the same name.
</ParamField>

***

## dotbot registry list

Lists all registered registries and the content they provide (workflows, stacks, tools, skills).

```powershell theme={null}
dotbot registry list
```

***

## dotbot registry remove

Removes a registered registry. Does not delete any content that was previously installed from the registry.

```powershell theme={null}
dotbot registry remove myorg
```

<ParamField path="<name>" type="string" required>
  Alias of the registry to remove.
</ParamField>

***

## dotbot update

Prints the commands needed to update the global dotbot installation. Dotbot tracks its install directory live via `$env:DOTBOT_HOME`, so a `git pull` in the checkout is the only step required.

```powershell theme={null}
dotbot update
```

<Note>
  This command prints update instructions - it does not run `git pull` automatically. After pulling, no reinstall step is needed. To upgrade in-project content overrides, run `dotbot workflow add <name> --force` for any workflows that ship project-tier files.
</Note>