@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

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

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