This page is a compact lookup table for the current basectl command surface.
Run basectl help <nested path> or append --help to that path for the same
leaf-specific usage. Run basectl --help for the journey-oriented command map.
Use space-separated values for long options, for example --format json.
Base rejects --option=value syntax before command delegation. Arguments after
-- belong to the delegated project command and may use that command's native
syntax.
basectl exposes -v as the public command-level debug switch. Direct
base_cli package standard options such as --debug, --quiet, --log-file,
--config, --environment, and --keep-temp are private to Python package
execution and are rejected by basectl.
Commands documented here are stable public CLI unless a focused feature
document explicitly marks the command, flag, output shape, or generated artifact
as experimental. Prefer documented --format json payloads for automation and
avoid scripting against human-readable tables, logs, or private base_cli
package options.
See Base Stability Tiers for the full stable, experimental, and internal support contract. The four read-only control-plane payloads using the shared v1 envelope are defined in Inspection JSON.
Base assumes Git as the source-control system. Non-Git SCMs such as Mercurial, Perforce, and Subversion are out of scope.
Base is GitHub-primary today. Local project commands work for non-GitHub Git
repositories once they are checked out locally and declare base_manifest.yaml.
Repository creation, cloning, configuration, issue, pull-request, Project, and
release automation are GitHub-specific unless a command explicitly says
otherwise. See
Source Control And Forge Support for the
full compatibility contract.
| Command | What it does | Important flags |
|---|---|---|
basectl setup [project] |
Install or reconcile Base and optional project artifacts. | --ci, --format <text|json>, --profile <dev,sre,ai>, --dry-run, --manifest <path>, --recreate-venv, --notify, --no-notify |
basectl update-profile |
Create, refresh, or remove Base-managed Bash and Zsh startup snippets, backing up existing dotfiles before changes. | --defaults, --no-defaults, --remove, --dry-run |
basectl update [project] |
Update a Base-managed project checkout through Git, or update Base through Homebrew when Base is Homebrew-managed, then run setup for the selected project. | --dry-run |
basectl onboard [project] |
Guide first-run setup through check, setup, shell profile, doctor, project discovery, and read-only manifest trust status. Defaults to base. |
--profile <list>, --dry-run, --yes, --no-profile |
basectl version |
Show the installed Base version. | none |
| Command | What it does | Important flags |
|---|---|---|
basectl projects list |
Discover Base-managed projects under the workspace root. | --workspace <path>, --format <text|json> |
basectl activate <project> |
Start an interactive Base Bash runtime shell for a project. | --workspace <path>, --no-cd |
basectl test [project] |
Run the project's declared test command from the project root. | --project <name>, --workspace <path>, --dry-run, -- <args> |
basectl run [project] <command> |
Run a named manifest command from the project root. | --project <name>, --workspace <path>, --dry-run, -- <args> |
basectl run [project] --list |
List runnable commands declared by a project manifest. | --project <name>, --workspace <path>, --format <text|json> |
basectl build [project] [target...] |
Run declared build targets, or build.default when no target is provided. |
--project <name>, --workspace <path>, --dry-run, -- <args> |
basectl build [project] --list |
List build targets declared by a project manifest. | --project <name>, --workspace <path>, --format <text|json> |
basectl demo [project] |
Run a project-owned demo script. | --project <name>, --workspace <path>, --dry-run, -- <args> |
basectl devcontainer [project] |
Preview or write .devcontainer/devcontainer.json from a Base manifest. Dry-run is the default. |
--workspace <path>, --format <text|json>, --write |
basectl devenv-report [project] |
Classify Base manifest fields for Nix/devenv planning without generating files or requiring Nix. | --workspace <path>, --format <text|json> |
basectl trust status [project] |
Show one project's manifest trust status, or all discovered command-bearing projects. | --workspace <path>, --format <text|json> |
basectl trust allow <project> |
Approve the current manifest command contract on this machine. | --workspace <path>, --manifest-sha256 <sha256> |
basectl trust revoke <project> |
Remove local manifest command approval. | --workspace <path> |
Manifest-declared test, run, build, demo, and activation surfaces are
project-owned code executed from the project root. Review manifests from
unfamiliar repositories before running them; use --dry-run or --list where
available and inspect activate.source directly before activation.
These four lifecycle commands use one project-selection order: --project <name>, then a backward-compatible first positional value when it names a
registered project, then the nearest base_manifest.yaml from the current
directory. If none applies, Base returns a controlled error. --workspace
changes where named projects are discovered; it does not replace nearest-
manifest traversal. From a workspace root with no project manifest, pass
--project <name> or a registered positional project.
For run and build, a registered first positional value keeps its legacy
project meaning even when the current manifest declares a command or target
with the same name. Select the current project explicitly to disambiguate, for
example basectl run --project current api or basectl build --project current api. Bash and Zsh completion use the same read-only resolution rules.
basectl run --list --format json and basectl build --list --format json
are stable, side-effect-free automation contracts. Each object has
schema_version: 1, a project object (name, root, manifest_path), and
an ordered commands or targets array. Each command item has name,
command, and runner (string or null). Each target item has name,
working_dir, command, description (string or null), and runner
(string or null). These keys are always present. Listing and completion
read manifest metadata only: they do not execute project commands or grant
manifest trust.
| Command | What it does | Important flags |
|---|---|---|
basectl setup --ci [project] |
Run setup with CI-safe defaults. Does not run tests or create runners/VMs. | --format <text|json>, --manifest <path>, --profile <list>, --recreate-venv |
basectl check [project] |
Verify Base and optional project readiness without making changes. Project checks record the latest result under ~/.base.d/<project>/checks/last.json. |
--ci, --profile <list>, --format <text|json>, --manifest <path>, --remote-network |
basectl doctor [project] |
Explain Base and optional project findings with stable finding IDs and fixes. | --ci, --profile <list>, --format <text|json>, --manifest <path>, --remote-network, --no-color |
basectl doctor explain <finding-id> |
Print local, deterministic guidance for a stable finding ID. | --format <text|json> |
basectl ci setup|check|doctor [project] |
Compatibility alias for the corresponding --ci mode command. |
Same options, help, validation, and exit codes as the target command. |
basectl logs |
List recent Base CLI runtime logs. | --command <name>, --limit <count> |
basectl logs last |
Print the latest failed command metadata plus a bounded redacted log tail. | --command <name>, --lines <count>, --format <text|json> |
basectl logs --path |
Print the newest matching log path only. | --command <name> |
basectl history |
List recent user-facing Base command history records. | --project <name>, --command <name>, --status <ok|warn|error>, --format <text|json>, --include-internal, --local-time |
basectl history --report |
Print a local Markdown or JSON activity report from history and log metadata. | --limit <count>, --format <markdown|json>, --local-time |
basectl logs --open |
Open the newest matching log in PAGER or EDITOR. |
--command <name> |
basectl logs --tail |
Tail and follow the newest matching log. | --command <name>, --lines <count> |
basectl clean |
Remove old Base runtime logs, temp files, and cache entries. | --older-than <age>, --keep-last <count>, --dry-run |
basectl config path |
Print the local Base config path. | none |
basectl config show |
Show local Base config as redacted JSON. | none |
basectl config doctor |
Diagnose local Base config. | none |
| Command | What it does | Important flags |
|---|---|---|
basectl workspace status |
Show read-only workspace project status and latest recorded project check dates. Uses workspace.manifest from user config unless --manifest is supplied. |
--workspace <path>, --manifest <path>, --format <text|json> |
basectl workspace check |
Run read-only checks across workspace projects. Uses workspace.manifest from user config unless --manifest is supplied. |
--workspace <path>, --manifest <path>, --format <text|json> |
basectl workspace doctor |
Run read-only diagnostics across workspace projects. Uses workspace.manifest from user config unless --manifest is supplied. |
--workspace <path>, --manifest <path>, --format <text|json> |
basectl workspace onboarding |
Summarize expected-repository first-day state and next actions without cloning or setup. Requires a configured or explicit workspace manifest. | --workspace <path>, --manifest <path>, --format <text|json> |
basectl workspace agent-brief |
Report local baseline, agent-guidance, AI-context, environment, and validation evidence for expected and extra Base-managed repositories without mutation or network calls. Requires a configured or explicit workspace manifest. | --workspace <path>, --manifest <path>, --format <text|json> |
basectl workspace clone |
Clone or validate expected repositories from a workspace manifest. Missing-repository materialization is GitHub-only today because this path delegates to repo clone. Uses workspace.manifest from user config unless --manifest is supplied. |
--workspace <path>, --manifest <path>, --include-optional, --dry-run |
basectl workspace pull |
Explicitly fetch and validate a canonical workspace manifest source before updating the local workspace manifest. Uses workspace.manifest_source and workspace.manifest from user config unless flags are supplied. |
--source <url-or-path>, --manifest <path>, --dry-run |
basectl workspace init <workspace-source> |
Initialize a workspace from a workspace configuration repository, update local workspace config, and optionally materialize member repositories. | --owner <owner>, --path <path>, --workspace <path>, --manifest <path>, --include-optional, --dry-run |
basectl workspace configure |
Apply the existing repo configure repair path across discovered Base-managed workspace repositories or an explicit workspace manifest. Skips missing, non-Base-managed, or non-GitHub repos and continues after per-repo failures. |
--workspace <path>, --manifest <path>, --dry-run |
This section is intentionally GitHub-specific except for local baseline inspection. Use ordinary Git to clone non-GitHub repositories, then use the daily project loop commands from the local checkout.
| Command | What it does | Important flags |
|---|---|---|
basectl repo init <name> |
Create a Base-managed repository baseline, including .github/base-project.yml, and optionally create/configure the GitHub repo. Use --path . for the current checkout; plain init does not commit or push local files, while --pr --issue <number> commits baseline changes on a canonical issue-backed branch, pushes it to origin, and opens a PR. Real PR runs derive the issue category; offline --pr --dry-run also requires --category <name>. Use --agent-ready to seed AGENTS.md and skills.md with the baseline. Use repeatable --language <csv> values to seed normalized project.languages metadata; selecting python also writes python.manager: uv. |
--path <path>, --repo <owner/name>, --issue <number>, --category <name>, --language <csv>, --description <text>, --copyright-holder <name>, --public, --private, --pr, --agent-ready, --project <title>, --project-owner <login>, --project-schema <schema>, --copy-project-fields-from <title>, --initiative-option <name>, --no-configure, --no-project, --no-protect-default-branch, --dry-run |
basectl repo clone <name-or-owner/name> |
Clone one GitHub repository into the configured Base workspace, treating matching existing checkouts as already satisfied. | --owner <owner>, --path <path>, --dry-run |
basectl repo check [path] |
Verify the local repository baseline. Stable inspection JSON uses the shared v1 envelope. | --agent-guidance, --agent-ready, --release, --format <text|json> |
basectl repo configure [path] |
Apply Base-managed GitHub repository settings, labels, default branch protection, non-default branch naming enforcement, the trusted issue/category branch policy workflow, and repo Project metadata. After a default-branch dispatch produces a recent trusted success, its GitHub-Actions-bound PR-head status becomes required. Reads .github/base-project.yml to seed options and fill missing issue defaults when present. |
--repo <owner/name>, --project <title>, --project-owner <login>, --project-schema <schema>, --copy-project-fields-from <title>, --initiative-option <name>, --replace-project, --no-project, --no-protect-default-branch, --dry-run |
basectl repo agent-guidance [path] |
Seed optional repo-local agent guidance files, optionally through a draft PR. Real PR runs derive the issue category; offline --pr --dry-run also requires --category <name>. |
--repo <owner/name>, --repo-name <name>, --default-branch <name>, --validation-command <cmd>, --issue <number>, --category <name>, --pr, --dry-run |
basectl repo installer-template [path] |
Write the maintained project installer starter script to a path, defaulting to ./install.sh, optionally through a draft PR. Real PR runs derive the issue category; offline --pr --dry-run also requires --category <name>. |
--print, --repo <owner/name>, --issue <number>, --category <name>, --pr, --dry-run |
basectl gh issue list |
List GitHub issues through gh. |
passes through gh options |
basectl gh issue create |
Create an issue with Base category conventions, assign it, and add repo Project metadata when the repo is known. Defaults to --category enhancement and Project Size=S when omitted. |
--category <bug|enhancement|documentation|ci|security>, --title <title>, --body <body>, --repo <owner/name>, --project <title>, --project-owner <login>, --size <T|S|M|L>, --no-project |
basectl gh issue readiness <number> |
Check whether an issue has the required body sections and, when Project coordinates are supplied, Base Project fields before assignment. Omitting Project coordinates reports a partial result. Stable inspection JSON uses the shared v1 envelope. | --repo <owner/name>, --project-owner <login>, --project-number <number>, --format <text|json> |
basectl gh issue start <number> |
Start the issue-backed branch workflow after verifying the issue has exactly one standard category; an explicit --category must match that label. The issue repository resolves from an explicit selector, then GH_REPO, then origin. |
--category <category>, --title <title>, --repo <owner/name>, -R <owner/name> |
basectl gh pr create/status/checks/ready/merge |
Create and manage pull requests through Base's workflow wrapper. pr create rejects a noncanonical current branch before invoking GitHub, auto-injects Fixes #<issue> unless --no-fixes is passed, and uses github.pr from base_manifest.yaml when present. |
passes through gh options; pr create also accepts --no-fixes |
basectl gh branch stale |
Report stale local branches. Stable inspection JSON uses the shared v1 envelope. | --days <days>, --format <text|json> |
basectl gh branch prune |
Prune safe merged branches. | --dry-run, --yes, --remote |
basectl gh worktree prune |
Prune stale merged worktrees. | --dry-run, --yes |
basectl gh project doctor |
Inspect GitHub Project metadata against the Base Project schema. | --project <title>, --owner <login>, --schema base-project |
basectl gh project configure |
Create or repair Base-managed Project metadata. | --project <title>, --owner <login>, --repo <owner/name>, --schema base-project, --config <path>, --copy-fields-from <title>, --replace-project, --initiative-option <name>, --dry-run |
basectl gh project issue set-fields <number> |
Add an issue to the Project if needed and update metadata fields. | --project <title>, --repo <owner/name>, --config <path>, field options |
| Command | What it does | Important flags |
|---|---|---|
basectl release check --version <version> |
Inspect release readiness without publishing. Stable inspection JSON uses the shared v1 envelope. | --manifest <path>, --format <text|json> |
basectl release plan --version <version> |
Print the release plan and downstream handoff details. | --manifest <path> |
basectl release notes --version <version> |
Extract release notes for the requested version. | --manifest <path> |
basectl release publish --version <version> |
Create the annotated Git tag and GitHub Release after checks pass. | --manifest <path>, --dry-run, --yes |
basectl docs |
Open the Base documentation home page on GitHub. | --show-url |
basectl export-context [project] |
Export a project's .ai-context/ directory as Markdown or Zip. |
--workspace <path>, --format <markdown|zip>, --output <path>, --print, --list-files |
basectl prompt list |
List repo-owned Markdown prompts that Base can render for AI-assisted workflows. | none |
basectl prompt product-self-review |
Print the periodic Base product self-review prompt with current Base metadata. | --output <path> |