# Set up from the terminal

> Connect your codebase to its IntentDocs spec from the terminal: log in, pick your project, and the CLI writes INTENT.md, ARCHITECTURE.md and a CI workflow that reports each test to its story.

Start with one command: `npx intentdocs login`. Below is a real session, replayed with the personal details swapped out.

## 1. Log in

Your browser opens and you approve this machine once. The terminal gets its own token, so you never paste a password or a key into it.

- The token is tied to the workspace you pick in the browser.
- Your own Anthropic key is optional, on any plan.

```
you@laptop ~ % cd ~/code/courtside && npx intentdocs login
Logging in to intentdocs...

Opening browser to authorize...
If it doesn't open, visit: https://www.intentdocs.com/cli/auth?code=••••••••

Waiting for browser approval....

✅ Logged in as user_•••••••• — token personal

You can now run: npx intentdocs init
Optional: add your Anthropic API key to unlock AI features on any plan — npx intentdocs keys set
```

## 2. Pick your project

init lists the projects you've specced on intentdocs.com. You type a number; nothing to copy, no ids to look up.

- It says which workspace you're reading from.
- Pick the project whose spec this code builds.

```
you@laptop courtside % npx intentdocs init

Fetching your projects...

Personal workspace — only you can see what's here.

Your projects:

  1. Pantry Pal
  2. Courtside
  3. Invoice Nudge
  4. Dog Walk Rota

Select project [1-4]: 2
```

## 3. Connect the map

This folder is now tied to the story map. INTENT.md is the spec your agent reads: every story and what “done” means for it, as a plain file in your repo.

- INTENT.md works without an account. It’s yours.
- .intent/ holds the local connection and is gitignored, so it never gets committed.

```
Fetching story maps...

Story maps in "Courtside":

  1. Courtside — Story Map

Select story map [1-1]: 1

Connecting to "Courtside — Story Map"...
✓ Connected to "Courtside — Story Map"
  22 stories — 3 done, 19 todo

✓ Downloaded INTENT.md
✓ Added .intent/ to .gitignore
```

## 4. Confirm your stack

It reads your repo and guesses the stack. Press Enter if it's right, or type yours. ARCHITECTURE.md records it, so your agent builds on what you have instead of picking a new framework.

- Edit ARCHITECTURE.md as you build.
- Then init prints what you can run next.

```
  Detected stack: Node.js (TypeScript)
  Is this correct? (press Enter to confirm, or type your stack):
  ✓ Created ARCHITECTURE.md with your stack (edit it as you build)

  ✅ Ready! Next steps:

    npx intentdocs status         — see your story map
    npx intentdocs next           — pick up the first story
    npx intentdocs setup          — configure Claude Code / Cursor slash commands
    npx intentdocs ci             — report your tests' results from CI to each story
    npx intentdocs propose        — plan a new feature from the terminal
```

## 5. Wire up CI

Say yes and it creates a CI key, writes a GitHub Actions workflow that runs your tests, and stores the key as a repo secret with gh. From then on, each test result lands on the story it proves.

- With gh signed in, the secret is stored for you.
- Not now? Run npx intentdocs ci later.

```
  Set up CI test reporting now? It creates a key and adds the workflow. (y/N): y

✓ Created a project CI key (shown once below — store it now).

✓ Wrote .github/workflows/intentdocs.yml — it runs your tests and reports each result to its story.

✓ Stored the key as the INTENTDOCS_CI_KEY repo secret with gh.
```

## 6. What's next

Your agent saves each test with its file and full name, so a CI result can find its story. After the next run on your default branch, ci --status shows how the results matched.

- The prompt for your agent is in the Prompt library.
- Nothing to configure by hand.

```
Tell your agent to save each test with its file and full name so CI results can reach the story — see the "Set up test reporting" prompt in the Prompt library.

After your next default-branch CI run, check how results matched with: npx intentdocs ci --status
```

## What you end up with

- `INTENT.md` (file) — The spec your agent reads: every story and its acceptance criteria.
- `ARCHITECTURE.md` (file) — Your stack, so the agent builds on it. Edit it as you go.
- `.github/workflows/intentdocs.yml` (file) — Runs your tests in CI and reports each result to its story.
- `.gitignore` (+ .intent/) — Keeps the local connection out of your commits.
- `INTENTDOCS_CI_KEY` (repo secret) — Lets CI report to your project. Stored with gh, never in a file.

## Then: build

- `npx intentdocs next` — Pick up the first story, with its acceptance criteria.
- `npx intentdocs setup` — Add slash commands to Claude Code or Cursor, like /intent-next, so your agent can do the same.
- `npx intentdocs ci --status` — After a CI run, see which test results reached which story.

Using an agent over MCP instead of the CLI? [Connect your AI tool](https://www.intentdocs.com/connect). Then follow [the day-to-day loop](https://www.intentdocs.com/day-to-day-loop), one story at a time.

## Get started

Sign up at https://www.intentdocs.com/sign-up, then run `npx intentdocs login` in your repo.