SwarmCraft
Install and ConnectGuide

Docs

Install the SwarmCraft CLI

Install the customer CLI from npm, sign in, check local prerequisites, and prepare Codex or Copilot for one-shot project work.

Use the SwarmCraft CLI when you want to prepare a repository and run a project board from the terminal. The CLI is the customer-facing download. Do not download or run apps/driver; that folder is internal SwarmCraft scenario and evidence tooling.

Requirements

Install these on the machine that owns the repository:

  • Node.js 20.19 or newer
  • npm
  • git
  • a SwarmCraft account with access to the project
  • a local repository with a clean git state
  • a working shell where git, node, npm, and your selected AI agent command are on PATH

The CLI is currently validated for macOS and Linux-style shells. On Windows, use WSL until native Windows shell support is explicitly documented.

Install from npm

For repeated use, install the CLI globally:

npm install -g @swarmcraftai/cli
swarmcraft --help

For a one-off check, use npx:

npx @swarmcraftai/cli --help

The npm package is @swarmcraftai/cli. The installed terminal command is swarmcraft.

Sign in

Sign in once before listing projects or preparing a repository:

swarmcraft auth login --email you@example.com

If your account requires MFA, pass a current code or a recovery code:

swarmcraft auth login --email you@example.com --mfa-code 123456
swarmcraft auth login --email you@example.com --recovery-code <recovery-code>

The CLI stores a local session under your home directory. Project data, tickets, and board changes still require SwarmCraft API authentication and authorization.

Check the setup

Run doctor from the repository you plan to use:

swarmcraft doctor --workspace . --agent-provider codex

Use copilot instead if that is your selected provider. The doctor command checks the local session, API reachability, git workspace, Node runtime, and selected agent command.

Prepare an AI provider

For Codex, install and authenticate the Codex CLI, then confirm this command works:

codex --help

SwarmCraft runs Codex with this default wrapper:

codex exec --sandbox workspace-write {command}

For Copilot, install and authenticate the Copilot CLI, then confirm this command works:

copilot --help

SwarmCraft runs Copilot with this default wrapper:

copilot --allow-all-tools --no-ask-user -p {command}

Use --agent-provider custom --agent-command '<command with {command}>' when your environment needs a different agent wrapper. The {command} placeholder receives the SwarmCraft packet-stage command.

Bootstrap first

After sign-in, list projects and prepare the repository:

swarmcraft projects list
swarmcraft init --project <project-id> --workspace .

init validates the repository, seeds .swarmcraft, Copilot, and Codex guidance files, creates packet files for non-done tickets, links those packets to SwarmCraft, and prints the next command.

When the repository is ready, continue with Run one-shot with the CLI.