Spiral Quickstart

1. Install the CLI

Requires Node.js 18+. You can also use npx @spiral/cli without installing globally.

2. Authenticate

A browser window opens for GitHub or email login. The CLI stores your session automatically.

3. Initialize your project

The CLI scans your codebase, creates a project on the Spiral server, extracts context into structured facts, and writes the following files:

• .spiral/config.json — Links this folder to your Spiral project
• .cursor/mcp.json — Connects Cursor's AI agent to your project
• .vscode/mcp.json — Same for VS Code
• CONTEXT.md — Your project's knowledge summary
• .cursor/rules — AI instructions tuned to your stack
• CLAUDE.md — Context for Claude-based agents
• .github/copilot-instructions.md — Context for GitHub Copilot
• .windsurfrules — Context for Windsurf

4. Open your IDE

Open the project in Cursor or VS Code. The IDE detects the MCP configuration and connects to Spiral automatically. On the first connection, a browser window opens for a one-time OAuth authorization — click Authorize and you're done.

Your AI agent now has access to 45+ Spiral tools — it can read your knowledge graph, write decisions, detect conflicts, and keep context synchronized across sessions.

5. Deep extraction (optional)

The initial spiral init captures surface-level context. For a comprehensive analysis — architecture patterns, API contracts, decision archaeology, and quality scoring — run deep extraction:

Next steps

• spiral status — View your project's health score and sync state
• spiral graph show — See your knowledge graph
• spiral facts list — Browse all extracted facts
• spiral sync — Synchronize after making changes