Getting started

SpecStrand turns ideas into reviewable, agent-executable plans and tasks. The spec CLI is a single binary that drives the work loop over the REST API for agents with shell access, CI jobs, and humans. This guide takes you from install to your first completed task.

1. Install

curl -fsSL https://specstrand.com/install.sh | sh

irm https://specstrand.com/install.ps1 | iex

The installer downloads from specstrand.com and verifies each file's checksum against the release manifest published there before installing; nothing is fetched from a third party.

Prefer to inspect the script first? Open the URL in a browser or pipe it to a pager before running it. With a Go toolchain and a source checkout, go install ./cmd/spec works too.

Confirm the install, and see which API the CLI targets:

spec version

Want a specific build instead? Install the CLI lists the direct downloads with their checksums, the supported platforms, and the install overrides.

2. Authenticate

Create a personal access token (PAT) in your SpecStrand settings and log in. The CLI already talks to https://api.specstrand.com, so there is nothing to point it at; SPEC_TOKEN (or a stored login) supplies the credential.

spec auth login --token <your-PAT>

Prefer an environment variable (CI, ephemeral shells)? Set SPEC_TOKEN instead of running spec auth login; it always wins over the stored token.

export SPEC_TOKEN=<your-PAT>
spec task next   # verifies the credential by claiming (or reporting no) work

Running against a different API, a local one for instance? Set SPEC_API, or pass --api on a single command. It is an override, never a requirement.

3. Drive your first work loop

Create a plan and a task or two, in the web app or by importing a checklist with spec plan import. Then let the CLI drain the project one task at a time:

spec project work --project <your-project>   # claim the next ready task
# read the task body + instructions, then do the work
spec task report --message "what you did / learned"
spec task complete --summary "what you did and how you VERIFIED it"

Repeat spec project work until it prints project drained (exit code 2): every plan is complete or the remaining work is blocked on you. Reporting also renews your lease, so report at each meaningful step. If you hit a decision only a human can make, don't guess:

spec task halt --question "the exact question" --handoff "what you did, what remains"

A human answers later and any agent resumes the same run with spec task next. For long builds and tests, wrap the command so your lease survives them: spec run -- go test ./....

4. Agents over MCP

The same work loop is available as an MCP server, so an MCP-capable agent can claim, report, and complete tasks with structured tools instead of shell commands. See the MCP setup docs to wire it into your agent.

Next

Read the documentation for the full CLI command reference, configuration and environment variables, and MCP setup.