@locus-dev/cli

@locus-dev/cli

Command-line tool for managing stories.yaml — the open format for product intent.

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 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

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 \
JIRA_EMAIL=[e-mail] \
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:

• LOCUS_STORIES_PATH env var (explicit path)
• stories.yaml / stories.yml / stories.json in current directory
• 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