First Draft CLI

firstdraft is the command-line client shared by First Draft agents and automation. It manages local Foundation Plan files, calls the versioned Service API, exposes reviewed analysis and GapSets, materializes verified Compilations, and coordinates private GitHub publication.

Start with the local development guide: install the CLI and Skill, then compile into your current folder with firstdraft plan compile --output .. No Drawing Board clone or GitHub push is required. The Drawing Board guide is the Codespaces fallback.

--output . is also the default, so firstdraft plan compile alone writes to the current folder. GitHub publication requires --github.

What this repository owns

• local Plan initialization, UUIDs, application keys, and source hashing;
• conditional whole-document push and conflict reporting;
• analysis polling and complete GapSet output;
• direct Compile-and-materialize and private publish orchestration;
• retained Compilation inspection and artifact download;
• terminal output, exit status, and recovery contracts;
• the dependency-free npm package; and
• package provenance and publication.

The Service owns Foundation Plan meaning and server-side lifecycle. Skills own the agent conversation. This repository owns the exact command and transport behavior between them.

Start with the right document

Task	Read first
Change the CLI	Agent instructions, then documentation map
Find a command or output contract	Command reference
Interpret an error or recover safely	Errors and recovery
Commit, review, or land a change	Contributing guide
Prepare or publish a package	Release runbook
See what changed in a version	Changelog
Report a vulnerability	Security policy

Run firstdraft --help or a command group's --help for concise terminal syntax.

Repository layout

Path	Responsibility
bin/	Published executable entrypoint
src/	Commands, API client, local Plan state, and output contracts
test/	Command, protocol, recovery, and package tests
scripts/	Test runner, package checks, and version sync
docs/	Documentation map and command and error references

Development

Development uses the Node.js and npm versions pinned in .tool-versions. Follow Work on the repository for the complete install, audit, and check sequence.

npm run check

The complete check runs type checking, ESLint, Prettier verification, tests, package allowlist validation, and a smoke installation of the packed tarball. Use the narrower scripts while iterating:

npm run typecheck
npm run lint
npm test
npm run pack:check
npm run pack:smoke

To exercise the checkout directly:

node bin/firstdraft.js --help

Remote commands default to production. Run firstdraft login (or firstdraft --staging login) once, or set FIRSTDRAFT_API_TOKEN / FIRSTDRAFT_STAGING_API_TOKEN. Existing Projects retain their saved origin. See environment selection for custom URLs and credential isolation. Keep tokens out of arguments, shell history, fixtures, snapshots, and logs.

Package contract

The published CLI supports Node.js 22 or newer. Direct automation callers can install the stable package with:

npm install --global @firstdraft.com/cli

Pin an exact compatible version when a repeatable installation matters. The changelog describes each version.

The published package:

• installs the firstdraft executable;
• runs reviewed JavaScript source directly;
• has no runtime dependencies or install scripts;
• performs no telemetry, update check, or network request unless the caller invokes an API command;
• reads Bearer credentials from the environment or its private firstdraft login credentials file; and
• carries npm provenance linking registry bytes to its GitHub workflow and commit.

The package includes this README, the documentation map, the command and error references, and the security policy. Repository files for maintainers stay out of it: AGENTS.md, the release runbook, the changelog, and the source-only release/compatibility.json. Inspect the packed file list whenever a source or documentation path moves.