Getting Started
Authentication
Spiral supports three authentication methods depending on your environment: browser login for development, OAuth for IDE agents, and tokens for CI/CD.
Browser Login (CLI)
For standard development, authenticate via the browser. The CLI opens a login page where you sign in with GitHub or email.
- The CLI opens a browser window to your Spiral dashboard
- Log in with GitHub or email
- Return to the terminal — you're authenticated
For self-managed instances, specify your server: spiral auth login --server https://your-instance.com/v1
IDE Authentication (MCP)
When your IDE connects to Spiral via MCP, authentication happens through OAuth 2.1 — no tokens to copy or configure.
- Open your project in Cursor or VS Code
- The IDE detects
.cursor/mcp.jsonand connects - A browser tab opens with a consent screen — click Authorize
- The session is cached. All future connections are automatic.
This is a one-time step. After authorizing, every project you open will connect without prompts.
Personal Access Tokens (CI / Scripts)
For headless environments like CI/CD pipelines, GitHub Actions, or server scripts, use a Personal Access Token (PAT).
- Go to Workspace → Settings → Tokens on the Spiral dashboard
- Click Create Token — give it a name and optional expiry
- Copy the token (starts with
sprl_). It's shown only once.
Alternatively, set the SPIRAL_TOKEN environment variable to authenticate without the login command.
$ spiral status