# Quickstart

> Install the CLI, write a Go CLI project from a stack, and hand it to your agent until verify comes back green.

This page installs the CLI and takes one Go CLI project from search to a green verify, with your coding agent doing the build.

## Requirements

You need:

- Node 22 or later, on macOS or Linux. `npm` and `npx` come with it.
- git.
- A coding agent on your PATH if you want stacks to hand the project over for you: Claude Code (`claude`) or Codex CLI (`codex`) are the best supported. Without one, stacks prints the prompt to give your agent yourself.
- The tools the stack builds with. This page uses `go-cli`, which needs Go and make. You can follow along without them; stacks warns about missing tools instead of failing.

## Install

The package on npm is `@steamfield/stacks`. The command it puts on your PATH is `stacks`.

```sh title="Terminal"
npm install -g @steamfield/stacks@latest
stacks --version
```

If you'd rather not install anything globally, put `npx @steamfield/stacks@latest` wherever this page says `stacks`. Every command works the same way, and the brief records the exact command your agent should use for `verify`.

The first time you run a command, stacks prints a one-time notice on stderr about anonymous usage telemetry. That run sends nothing. If you don't want it, turn it off now:

```sh title="Terminal"
stacks telemetry disable
```

The [telemetry page](https://stacks.steamfield.io/telemetry/) lists what's collected and every [off switch](https://stacks.steamfield.io/telemetry/#opt-out).

## Find a stack

A stack is a recipe for one kind of project. Describe what you want in plain words:

```sh title="Terminal" group="search"
stacks search "Go command line tool" --kind stack --limit 3
```

```text title="Output" group="search"
stack go-cli (strong)
A Go command-line tool with subcommands, configurable settings, actionable errors and human or JSON output.
Why: cli (platforms); cli-tool (productKinds); Go (id, name, tags); Go command line (description, summary); Go command (body); command (requests, goodFor); command line (useCases)
...
stack typescript-cli (strong)
A compiled command-line tool with subcommands, JSON results, lazy configuration and structured logs.
...
Next: stacks show go-cli, then stacks new go-cli <dir>.
```

Each hit says how well it fits (`strong` or `partial`) and why: which of your words matched which part of the entry. `search` asks the hosted API at stacks.steamfield.io and ranks locally at the same time, so it still works offline. `stacks list stacks` prints the whole catalog, and you can browse it at [stacks.steamfield.io/stacks/](https://stacks.steamfield.io/stacks/).

## Review the stack

`stacks show` prints the whole recipe without writing anything:

```sh title="Terminal" group="show"
stacks show go-cli
```

```text title="Output" group="show"
Go CLI (go-cli), stack, origin bundled, trusted
A starter for a terminal program written in the Go language, with settings and clear error messages.
...
Tools: go, make, git, golangci-lint
Decisions:
  - Binary name: the project slug (default; the Makefile's BIN).
  - Coverage floor: 50% (default).
  ...
Fragments: required none; default agent-ops, git-hooks, ci-github; optional goreleaser, rr, ce-plugin
Verify:
  install: make install (phase setup, layer install)
  build: make build (layer build)
  vet: make vet (layer typecheck)
  lint: make lint (layer lint)
  test: make test (layer test)
  ...
```

`Decisions` lists what your agent will ask you, each with a default. `Fragments` lists the add-ons the stack pulls in, and `Verify` lists the checks that must pass before the project counts as done.

## Preview the project

A dry run composes everything and writes nothing:

```sh title="Terminal" group="dry"
stacks new go-cli my-cli --sandbox --dry-run
```

```text title="Output" group="dry"
Planned my-cli from go-cli (sandbox).
Fragments: agent-ops, ci-github, git-hooks
Agents: claude
Git: would create a new repository
Would write 20 files:
  .claude/ (10 files)
  .editorconfig
  .gitignore
  .stacks/ (4 files)
  AGENTS.md
  CLAUDE.md
  Makefile
  README.md
Brief: .stacks/BRIEF.md (3272 words)
Dry run: nothing was written.
```

`--sandbox` means local only. Your agent takes the default for every decision instead of asking you, deploy and release fragments stay out, and nothing is published. It's the fastest way to see a stack working. Leave it off for a real project, where the brief lists the decisions your agent should bring to you.

## Create the project

Run the same command without `--dry-run`:

```sh title="Terminal" group="new"
stacks new go-cli my-cli --sandbox
```

```text title="Output" group="new"
Created my-cli from go-cli (sandbox).
Fragments: agent-ops, ci-github, git-hooks
Agents: claude
Git: new repository, nothing committed
Brief: .stacks/BRIEF.md (3272 words)
...
```

stacks writes the starter files, runs `git init`, and starts your coding agent in `my-cli/` with one instruction: read `.stacks/BRIEF.md` and carry it out. From here you're talking to the agent.

If you'd rather start the agent yourself, add `--no-launch` (in a fresh directory). stacks prints the prompt instead, and you open `my-cli/` in your agent and paste it.

```sh title="Terminal"
stacks new go-cli my-cli --sandbox --no-launch
```

The agent works through the brief: it writes the code, installs current versions of the packages the stack names, and runs `stacks verify` after each round of fixes. Your part is answering the questions the brief tells it to ask. With `--sandbox` there are none.

## The files in `.stacks/`

Most of what `new` wrote is ordinary project files: a `Makefile`, `README.md`, `AGENTS.md`, Claude Code settings and hooks under `.claude/`. The part stacks owns is `.stacks/`:

| File | What it is | Committed |
| --- | --- | --- |
| `BRIEF.md` | The agent's task: what to build, which decisions to ask about, and the checks that must pass | No |
| `manifest.json` | Which stack and fragments the project came from, and its verify steps | Yes |
| `NOTES.md` | Where the agent records questions it asked you and problems it found in the brief | No |
| `state/` | Verify's run history | No |

The brief runs to a few thousand words, written for the agent to read in full. Skim its "Decisions" and "Definition of done" sections to see what you're getting. [The brief and the manifest](https://stacks.steamfield.io/docs/concepts/brief-and-manifest.md) covers both files.

## Run verify yourself

`verify` runs the steps in the manifest and reports which pass. You can run it at any point:

```sh title="Terminal"
cd my-cli
stacks verify --all
```

Run it straight after `new` and it fails at the first setup step, because the agent hasn't written anything yet. That's expected. Once the agent is done, the same command ends with outcome `green` and exit 0.

`--all` also runs the steps a sandbox project skips by default. Use it for the final check. A run limited with `--only` or `--skip-tag` can exit 0 with outcome `partial`, and partial never counts as done.

> [!IMPORTANT]
> Your agent can't edit the verify steps to get a pass. verify compares the steps against a copy recorded outside the project and refuses to run when they differ. If you change a step on purpose, accept it from your own terminal with `stacks verify --accept-changes`; agents are refused. [Verify](https://stacks.steamfield.io/docs/concepts/verify.md#tamper-evidence) explains how.

A green verify proves the declared checks pass. Read the code your agent wrote the way you'd review any change.

## View the verify history

```sh title="Terminal"
stacks runs
```

`runs` summarizes the project's verify runs: how many there were, the last outcome, how long it took to reach the first green run, and how many times the agent had to ask you something.

## Uninstall

Remove the CLI with npm:

```sh title="Terminal"
npm uninstall -g @steamfield/stacks
```

stacks also keeps a few directories in your home folder. Delete the ones you don't want:

| Path | What it holds |
| --- | --- |
| `~/.config/stacks/` | `config.json` and your own stacks and fragments |
| `~/.local/share/stacks/` | Data |
| `~/.local/state/stacks/` | Project state records and telemetry state |
| `~/.cache/stacks/` | Cached index, stats and search data |
| `~/.claude/skills/stacks/` | The agent skill, if you installed it |

If you've set `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME` or `XDG_CACHE_HOME`, the directories live under those instead. `stacks doctor` prints the paths it uses. Projects you created keep working without stacks; only `stacks verify` needs it.

## Next steps

- [Use stacks with your agent](https://stacks.steamfield.io/docs/agents.md): let your agent pick the stack and run the commands.
- [Add to an existing repository](https://stacks.steamfield.io/docs/guides/existing-repo.md): apply fragments such as CI to a project you already have.
- [How stacks works](https://stacks.steamfield.io/docs/concepts.md): stacks, fragments, composition and presets.
- [CLI commands](https://stacks.steamfield.io/docs/reference/commands.md): every command and flag.