.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.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.
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.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.switch
Refreshes workflow and stack selections in
.bot/.control/settings.json and rewrites .bot/.gitignore. Workspace data under .bot/workspace/ is never touched.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.switch
Previews what would be created without writing any files.
dotbot list
Lists all available built-in workflows and stacks, plus any content from installed registries.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.int
Preferred port for the dashboard UI. Overrides the default auto-selection.
switch
Opens the dashboard in the default browser after the server starts.
switch
Starts the UI server without also starting the HTTP runtime.
dotbot run
Runs or reruns a named workflow that is installed in the project. Equivalent todotbot workflow run.
string
required
Name of the installed workflow to run. Use
dotbot workflow list to see all installed workflow names.switch
Keeps the process attached and streams progress output until the workflow completes or is stopped.
switch
Does not automatically start the HTTP runtime before running the workflow.
int
Interval in milliseconds between status polls in watch mode. Defaults to 1000.
dotbot workflow run
Runs or reruns a named workflow. Identical todotbot run - both invoke the same underlying script.
dotbot workflow add
Adds a new workflow to a project that was already initialised withdotbot init. Useful when a team wants to layer additional pipelines on top of an existing installation.
string
required
Workflow name, either a built-in name or a registry-qualified name in the form
registry-alias:workflow-name.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.
string
required
Name of the installed workflow to remove.
dotbot workflow list
Lists all workflows currently installed in the project.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.
dotbot tasks stop
Signals the workflow-agnostic task runner to stop after the current task completes.dotbot resume
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.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.
string
API key for authenticating with the mothership dashboard.
Press Ctrl+C to stop the runtime. On exit it removes
.bot/.control/runtime.json so the next start gets a fresh connection file.dotbot runtime-status
Shows the current state of the per-project HTTP runtime: PID, URL, start timestamp, and a list of active workflow runs.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.dotbot prune-branches
Deletes staleworkflow/* 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.
string
Age threshold for candidate branches. Accepts values like
30d, 7d, 2w. Defaults to 30d.string
Which branch prefix to consider:
workflow, task, or all. Defaults to all.switch
Prints candidate branches without deleting them.
switch
Includes branches that have a remote-tracking counterpart (
origin/<name>). Excluded by default.switch
Skips the confirmation prompt.
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.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.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.Run
dotbot doctor after a crash or unexpected stop to identify stale locks before retrying a workflow.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.
string
Path to an alternative dotbot checkout to copy from. Defaults to
$env:DOTBOT_HOME.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.string
required
Content type to install:
agent, prompt, or skill. Plural forms (agents, prompts, skills) are also accepted.string
Name, local path, registry path, or GitHub URL of the content to install.
string
Fully-qualified source URL including an optional version tag (e.g.
github.com/owner/repo/skills/name:v2).string
Version tag to install when the source provides versioned releases.
switch
Installs into
$env:DOTBOT_HOME rather than the current project. Makes the content available to all projects on this machine.switch
Overwrites an existing installation at the target location.
dotbot registry add
Links an enterprise extension registry so that its workflows, stacks, tools, and skills become available viadotbot 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.
string
required
Short alias used to reference the registry (e.g.
myorg). Qualify workflow names with this alias when installing: myorg:custom-workflow.string
required
Git URL or local filesystem path to the registry root. The directory must contain a
registry.yaml manifest.string
Git branch to track. Defaults to the remote’s default branch.
switch
Overwrites an existing registry registration with the same name.
dotbot registry list
Lists all registered registries and the content they provide (workflows, stacks, tools, skills).dotbot registry remove
Removes a registered registry. Does not delete any content that was previously installed from the registry.string
required
Alias of the registry to remove.
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.
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.