@locus-dev/cli

Command-line tool for managing stories.yaml — a specification format for software requirements that lives in your repo as the single source of truth. Like unit tests, but for what the product is supposed to do.

npm i -g @locus-dev/cli

Commands

locus init              Create a stories.yaml scaffold in the current repo
locus list              List all stories (table format)
locus add               Interactive story creation wizard
locus onboard           Multi-source generator: GitHub + Linear + Jira + free text
locus infer             Infer stories.yaml from a codebase or GitHub repo
locus audit             Detect drift between code and stories.yaml
locus coverage          Show coverage % and breakdown
locus validate          Validate stories.yaml against the spec
locus sync --linear     Push stories to Linear
locus sync --github     Push stories to GitHub Issues
locus sync --jira       Push stories to Jira
locus sync --notion     Push/pull stories with Notion

Usage

Onboard — generate stories.yaml from what you already have

Solves the cold-start problem: connect existing sources and Locus generates a coherent stories.yaml.

# From a GitHub repo (reads tests, routes, README)
locus onboard --github myorg/myrepo --output stories.yaml

# From a local directory
locus onboard --dir ./src --output stories.yaml

# From Linear issues
LINEAR_API_KEY=lin_api_xxx locus onboard --linear --output stories.yaml

# Full multi-source: GitHub + Linear + free-text description
LINEAR_API_KEY=lin_api_xxx \
  locus onboard \
  --github myorg/myrepo \
  --linear \
  --text "Users can sign up, create projects, invite teammates" \
  --output stories.yaml

# Cold start: just describe your product
locus onboard --text "Users can sign in with Google, manage projects, assign tasks" --output stories.yaml

Each generated story is annotated with _confidence, _sources, and any _conflicts found across sources. Review and remove annotations before committing.

Initialize

locus init

Creates a stories.yaml with the Locus JSON Schema header so editors validate it inline.

List stories

locus list
locus list --status not-implemented
locus list --section Auth
locus list --json

Add a story

Interactive:

locus add

Or with flags (non-interactive):

locus add --id auth-sso --title "SSO login" --section Auth --status not-implemented

Audit for drift

Scan your codebase and flag stories that may be drifting from reality:

locus audit
locus audit --dir ./src --ext ts,tsx
locus audit --story auth-sso
locus audit --json

Coverage

locus coverage
locus coverage --section Auth
locus coverage --json

Validate

locus validate

Exits non-zero on any error — safe to add to CI.

Sync

Push stories to your issue tracker:

# Linear
LINEAR_API_KEY=lin_api_xxx locus sync --linear

# GitHub Issues
GITHUB_TOKEN=ghp_xxx GITHUB_REPOSITORY=owner/repo locus sync --github

# Jira
JIRA_HOST=https://acme.atlassian.net \
[email protected] \
JIRA_TOKEN=xxx \
JIRA_PROJECT_KEY=LOCUS \
locus sync --jira

# Notion — push stories.yaml → Notion database (upsert)
NOTION_TOKEN=secret_xxx \
NOTION_DATABASE_ID=your-database-id \
locus sync --notion

# Notion — pull Notion rows → stories.yaml (new stories only)
NOTION_TOKEN=secret_xxx \
NOTION_DATABASE_ID=your-database-id \
locus sync --notion --pull

Notion database setup

Your Notion database needs these properties:

| Property | Type | Notes | |---|---|---| | Name | title | Page title (auto-populated) | | Story ID | text | Canonical story identifier | | Status | select | Not Implemented / Partial / Implemented / Stale / Deprecated | | Priority | select | Critical / High / Medium / Low | | Description | text | Optional | | Section | text | Optional | | Depends On | text | Optional | | Design Ref | url | Optional |

Share the database with your Notion integration (Settings → Integrations).

File discovery

locus discovers stories.yaml automatically:

1. LOCUS_STORIES_PATH env var (explicit path)
2. stories.yaml / stories.yml / stories.json in current directory
3. Walk up to git root

Related

• @locus-dev/mcp-server — MCP server for Claude Code, Cursor, Windsurf
• JSON Schema — machine-readable spec validator
• Spec — the Locus story format spec
• GitHub Action — CI drift detection on every PR

License

MIT