Installing the specify CLI: Persistent vs One-time Setup

Before running a single github spec kit command, we need to install the specify CLI and configure it properly. This sounds simple, but there are several setup options with different implications — especially for developers working across multiple projects simultaneously.

This article walks through every option, from the simplest to the most robust, plus troubleshooting for the problems you’re most likely to hit.

02.1 Two Installation Modes: Global vs Project-Level

The first decision is where the CLI lives. Global mode installs it once for your whole machine and is what most developers want — the command below installs it and confirms the version.

1npm install -g @github/spec-kit
2specify --version

Project-level mode instead pins the CLI as a dev dependency inside one repository, which is what teams reach for when they need everyone on the exact same version. The commands below install it locally and run it through npx.

1npm install --save-dev @github/spec-kit
2npx specify --version

We use global mode throughout this series because it’s more practical for a tool you invoke across many projects — but keep project-level in mind for the version-locking scenario we revisit in 02.12.

02.2 Node.js Prerequisites

The specify CLI runs on Node.js, so before installing anything, confirm you’re on a supported version. The two checks below print your current Node and npm versions.

1node --version  # minimum v18.0.0
2npm --version   # minimum 8.x.x

If Node isn’t installed — or is too old — the cleanest fix is nvm, which lets you install and switch Node versions without touching system packages. The commands below install nvm and the latest LTS.

1curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
2nvm install --lts && nvm use --lts

The takeaway: get on Node 20 LTS via nvm now, and you’ll avoid the version-mismatch errors that account for a large share of “specify won’t install” reports.

02.3 Install the specify CLI

With Node ready, installing the CLI is a single command — the block below installs it globally and then explores what it can do.

1npm install -g @github/spec-kit
2specify --version
3specify --help

For reference, specify --help exposes the full command surface you’ll be using: constitution, feature, clarify, plan, tasks, implement, plus the helpers config, validate, and changelog. Knowing these names up front makes the rest of the topic easier to follow.

02.4 API Key Configuration: Three Options

The CLI needs an Anthropic API key to talk to Claude, and there are three ways to provide it. The most robust is an environment variable, shown below, because it applies to every terminal session and never lands in a committed file.

1echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.bashrc
2source ~/.bashrc

The second option is a per-project .env file — handy when different projects bill against different keys. The commands below create it and, critically, add it to .gitignore.

1echo "ANTHROPIC_API_KEY=sk-ant-api03-..." > .env
2echo ".env" >> .gitignore

The third option stores the key in Spec Kit’s own global config, which is convenient but keeps a plaintext key on disk:

1specify config set api-key sk-ant-api03-...

The rule to remember: prefer the environment variable for daily work, reach for .env only when you truly need per-project keys, and never commit any of them.

02.5 Project Configuration File

Beyond the key, each project can carry its own defaults in a specify.config.json at the repo root. The file below pins the model, language, architecture, output paths, and a post-implement hook.

 1{
 2  "model": "claude-sonnet-4-20250514",
 3  "language": "go",
 4  "architecture": "clean",
 5  "output": {
 6    "spec_dir": ".specify",
 7    "code_dir": "internal"
 8  },
 9  "hooks": {
10    "post_implement": "go build ./... && go vet ./..."
11  }
12}

The most valuable line here is the post_implement hook: it automatically verifies that generated code compiles and passes go vet after every implementation phase, so broken output is caught the moment it’s written rather than at review time.

02.6 Verify Setup

Before pointing the CLI at real work, do a dry run that exercises the API connection without creating any files. The command below tests connectivity and prints exactly what would happen.

1# Test connection without creating files
2specify constitution init --dry-run
3
4# Expected output:
5# ✓ Connecting to Anthropic API...
6# ✓ API connection successful
7# [DRY RUN] Would create .specify/constitution.md

If you see the two green check marks, your install, key, and network path are all healthy — if not, jump straight to the troubleshooting section in 02.11.

02.7 Shell Autocomplete

A small quality-of-life step is enabling tab-completion for commands and feature names. The snippet below wires it up for bash and zsh.

1# Bash
2specify completion bash >> ~/.bashrc && source ~/.bashrc
3
4# Zsh
5specify completion zsh >> ~/.zshrc && source ~/.zshrc

Once this is in place you can tab through subcommands and flags instead of memorizing them, which pays off constantly given how often you’ll type specify implement.

02.8 Complete Setup Validation Script

Rather than checking each dependency by hand, it’s worth scripting the whole verification. The script below asserts Node, the CLI, the API key, and Go are all present.

1#!/bin/bash
2echo "=== Specify CLI Setup Check ==="
3node --version && echo "✅ Node.js OK" || echo "❌ Node.js missing"
4specify --version && echo "✅ specify CLI OK" || echo "❌ specify missing"
5[ -n "$ANTHROPIC_API_KEY" ] && echo "✅ API key set" || echo "❌ API key missing"
6go version && echo "✅ Go OK" || echo "❌ Go missing"

Keep this script in your dotfiles: running it on a new machine turns “why doesn’t specify work here?” into a four-line diagnosis instead of a scavenger hunt.

02.9 Model Selection Guide

Spec Kit lets you pick a different Claude model per command, trading cost against reasoning depth. The table below maps each command to a recommended model and why.

To act on that table, override the model per invocation as shown below — heavier models for planning, cheaper ones for mechanical steps.

1specify plan product-service --model=claude-opus-4-6          # for complex features
2specify tasks product-service --model=claude-haiku-4-5-20251001  # for speed

The principle: spend model budget where reasoning matters most (planning and clarification) and economize on the mechanical steps.

02.10 CI/CD Setup

Spec Kit isn’t only an interactive tool — it can run inside a pipeline to validate that code still matches its spec. The workflow fragment below installs the CLI and runs a validation step with the key injected from secrets.

1- name: Install specify CLI
2  run: npm install -g @github/spec-kit
3
4- name: Validate spec compliance
5  env:
6    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
7  run: specify validate --feature=product-service

Note the key comes from secrets, never from the repo — this is the CI-safe version of the local setup, and we go deep on it in Article 19.

02.11 Troubleshooting

Most install failures fall into four buckets, and each has a one-line fix. When specify is installed but not found, your PATH is missing the npm global bin directory — the export below repairs it.

1# command not found: specify
2export PATH="$(npm config get prefix)/bin:$PATH"

The next two — a missing key and a corporate proxy blocking the API — are equally quick to resolve:

1# ANTHROPIC_API_KEY not set
2export ANTHROPIC_API_KEY="sk-ant-api03-..."
3
4# Connection timeout (behind a proxy)
5export HTTPS_PROXY=http://proxy.company.com:8080

Finally, if the key is rejected, verify it directly against the API before assuming Spec Kit is at fault — the curl below is the ground truth.

1# Invalid API key — test directly
2curl -X POST https://api.anthropic.com/v1/messages \
3  -H "x-api-key: $ANTHROPIC_API_KEY" \
4  -H "Content-Type: application/json" \
5  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

The pattern across all four: isolate whether the failure is PATH, key, network, or credential, and you’ll fix installation problems in seconds instead of guessing.

02.12 Global vs Project-Level Comparison

With both modes now covered, the table below puts them side by side so you can choose deliberately rather than by default.

The decision rule: go global as an individual moving between projects; go project-level the moment a team needs everyone pinned to the same CLI version.

02.13 Security Best Practices

Your Anthropic key is a billing credential, so treat it like a password. The checklist below distills the do’s and don’ts.

1# ❌ NEVER: Hardcode in committed files
2# ❌ NEVER: Paste in chat/Slack/Teams
3# ✅ DO: Store in a password manager
4# ✅ DO: Use an environment variable from ~/.bashrc
5# ✅ DO: Rotate regularly
6# ✅ DO: Create separate keys per environment
7# ✅ DO: Set a spending limit in the Anthropic console

The single highest-leverage item: set a monthly spending limit in the console — it turns a leaked or runaway key from a financial incident into a capped annoyance.

02.14 Useful Aliases

If you run these commands dozens of times a day, short aliases add up. The block below maps each subcommand to a two- or three-letter shortcut.

1alias spc="specify"
2alias spcf="specify feature"
3alias spcc="specify clarify"
4alias spcp="specify plan"
5alias spct="specify tasks"
6alias spci="specify implement"

Drop these in your shell profile and the six-command cycle becomes muscle memory rather than typing overhead.

02.15 Updating the specify CLI

Spec Kit evolves quickly, so knowing how to update — and how to not update carelessly — matters. The commands below update, inspect the changelog, and pin a version respectively.

1# Update to latest
2npm update -g @github/spec-kit
3
4# Check changelog before updating
5specify changelog
6
7# Pin to a specific version
8npm install -g @github/spec-kit@1.x.x

The rule: always read the changelog before updating, because breaking changes can alter the format of an existing .specify/ folder you’ve already committed.

02.16 Multi-Project Setup

One of the payoffs of a global install is that a single CLI serves every project while each repo keeps its own defaults. The commands below show the same command producing different behavior in two projects.

1cd ~/projects/santekno-shop && specify constitution init
2# Uses santekno-shop/specify.config.json
3
4cd ~/projects/dashboard && specify constitution init
5# Uses dashboard/specify.config.json

The takeaway: the CLI is global but the configuration is local, so per-project model, architecture, and path settings never bleed across repositories.

02.17 Windows Setup

Windows users get the same experience with two small differences. The PowerShell command below sets a persistent user-level environment variable for the key.

1[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-api03-...', 'User')

For Node itself, nvm-windows is the recommended version manager — with those two pieces in place, every other command in this article works unchanged.

02.18 Santekno Shop Project Setup

Now we apply all of the above to the real project. The commands below initialize the Go module, scaffold the clean-architecture folders, and confirm the CLI runs inside the repo.

1cd santekno-shop
2go mod init github.com/santekno/santekno-shop
3mkdir -p internal/{domain,usecase,repository,delivery/http}
4mkdir -p cmd/server .specify/features
5
6# Verify specify runs in this project
7specify --version  # ✓

With this scaffold in place, Santekno Shop is ready for the specify constitution init we run in Article 05 — but first we need to understand what that command produces, which is Article 03.

02.19 The –verbose Flag for Debugging

When output surprises you, --verbose is the fastest way to see exactly what the CLI sent to Claude. The command below turns it on for a plan run.

1specify plan product-service --verbose

With verbose enabled, Spec Kit prints the exact prompts, the constitution and spec content it included, the raw API response, and any post-processing it applied — making it invaluable for diagnosing “why did it generate that?” moments.

02.20 Summary

Installing the specify CLI is straightforward, but the handful of choices along the way shape your long-term workflow.

Recommended setup for most developers:

1. Install Node.js 20 LTS via nvm
2. npm install -g @github/spec-kit
3. Set ANTHROPIC_API_KEY in ~/.bashrc or ~/.zshrc
4. Run specify --version to verify
5. Create specify.config.json per project

Key distinction: Global install for individual developers moving between projects; project-level for teams needing version consistency.

Security: Treat the API key like a password — store it in a password manager, set spending limits, and rotate it periodically.

In the next article, we examine the files Spec Kit generates in detail — the anatomy of every output and how they relate to each other.