CLI reference

Install

The CLI requires Node.js 20 or newer. Install the packaged release from GitHub, replacing <version> with the release you want.

npm install -g https://github.com/pat-baseten/draftstack/releases/download/v<version>/draftstack-<version>.tgz
draftstack --version

The Installation page under Getting started covers sign-in after the install.

Global options

Every command accepts these options:

• --api-url <url>: DraftStack API URL. Defaults to https://draftstack-dev.vercel.app.

• --output <format>: Output format: text, json, jsonl, or ndjson. Use json for scripts and agents.

• --fields <fields>: Comma-separated top-level fields to include in output.

• --verbose: Write diagnostic output to stderr.

Authentication

draftstack auth login: Opens a browser login flow and stores a local CLI token.

draftstack auth login --no-open: Prints the login URL instead of opening a browser, then waits for completion. Use it on headless or remote machines.

draftstack auth status: Shows the active API URL and login state.

draftstack auth logout: Removes stored auth for an API host.

API tokens

API tokens authenticate direct /api/v1 requests and the MCP server.

draftstack auth tokens create --name <name> --scope <scope>: Creates an API token. Repeat --scope for multiple scopes, and set --expires-at <iso-date> to limit its lifetime. The token value is shown once; store it securely.

draftstack auth tokens list: Lists API tokens with their scopes and expirations.

draftstack auth tokens revoke <token-id>: Revokes an API token.

GitHub setup

draftstack setup github: Opens the GitHub App installation flow in a browser.

draftstack setup github --print-url: Prints the GitHub App installation URL instead of opening a browser.

draftstack setup github --no-open: Prints the installation URL and does not open a browser. Use it on headless or remote machines.

Repositories

draftstack repos list: Lists repositories the installed GitHub App can access.

draftstack repos docs-paths <repo>: Detects documentation paths in a repository.

draftstack repos validate-docs <repo>: Validates that DraftStack can write to a documentation repository.

Projects

draftstack projects list: Lists projects.

draftstack projects get <project-id>: Shows project details.

draftstack projects create: Creates a project from flags for the docs repository and monitored repositories.

draftstack projects repos add <project-id> <repos...>: Adds monitored repositories to a project.

draftstack projects api-key set <project-id> --env BASETEN_API_KEY: Stores the model API key for a project from an environment variable.

draftstack projects backfill <project-id> --days 7: Queues recent merged pull requests for analysis.

draftstack projects pr-mode set <project-id> auto: Sets the default publish mode for a project so approvals do not need the flag. Use inherit to clear it. The mode resolves most specific first: the per-call flag, then the project, team, and organization defaults, then draft.

Sites

draftstack sites create --repo <docs-repo> --source-repo <owner/repo>: Creates or updates a generated static docs site and registers the DraftStack project. Add --force to overwrite existing generated files.

Suggestions

draftstack suggestions list --project <project-id>: Lists suggestions for review.

draftstack suggestions get <suggestion-id>: Shows full suggestion details, including affected files and reasoning.

draftstack suggestions diff <suggestion-id> [file-id]: Shows the proposed change as a unified diff, for one file or all files.

draftstack suggestions approve <suggestion-id>: Publishes an approved suggestion. Control publishing with --pr-mode: draft opens a draft pull request (the default), auto opens a pull request and merges it immediately, none commits a branch without opening a pull request.

draftstack suggestions dismiss <suggestion-id> --reason <reason>: Dismisses a suggestion. Give a substantive reason; scheduled audits distill dismissal reasons into suggested project knowledge rules.

MCP server

draftstack mcp: Runs the API-backed MCP server over stdio so agents can list projects, inspect suggestions, view diffs, approve, and dismiss with a scoped API token.