linearis (Story Industries fork)

A CLI tool for Linear.app with JSON output, smart ID resolution, and optimized GraphQL queries. Designed for LLM agents (Claude Code, etc.) and humans who prefer structured data.

Modified by Francesco La Ferla for Story Industries. Based on linearis by Carlo Zottmann (MIT license).

What's different from upstream

The original linearis had limited write operations. This fork adds full CRUD across all entities:

Entity	Added operations
Initiatives	Entirely new command group (list, read, create, update, delete, archive, unarchive, link-project, unlink-project)
Issues	delete, archive, unarchive
Projects	read, update, delete, archive, unarchive
Comments	list, update, delete
Labels	create
Cycles	create, update, archive
Project Milestones	delete

---

Setup

1. Install

npm install -g storyindustries/linearcli

Requires Node.js >= 22.

2. Create your Linear API token

1. Go to linear.app/settings/api
2. Click "Create key"
3. Give it a label (e.g., "CLI" or "Claude Code")
4. Copy the token (starts with lin_api_)

3. Save the token

Create a file at ~/.linear_api_token containing just the token:

echo "lin_api_YOUR_TOKEN_HERE" > ~/.linear_api_token
chmod 600 ~/.linear_api_token

The chmod 600 ensures only your user can read it.

4. Verify

linearis teams list

You should see the Story-industries team (key: STO).

---

Usage

All commands return JSON. Use linearis --help for the full list, or see LINEARIS_AGENT_GUIDE.md for the complete reference.

Quick examples

# List recent issues
linearis issues list --limit 10

# Read an issue
linearis issues read STO-123

# Create an issue
linearis issues create "Fix login bug" \
  --team "STO" \
  --description "Users can't log in on Safari" \
  --priority 2

# Update status
linearis issues update STO-123 --status "In Progress"

# Add a comment
linearis comments create STO-123 --body "Started working on this"

# Search
linearis issues search "onboarding" --team "STO"

Authentication options

The CLI reads the API token from (in order of precedence):

1. --api-token <token> flag (per-command)
2. LINEAR_API_TOKEN environment variable
3. ~/.linear_api_token file (recommended)

Important: Each person must use their own token. Never share tokens.

---

Claude Code integration

To use linearis with Claude Code, add the following to your project's CLAUDE.md:

## Linear

- **CLI:** `linearis` (installed globally via npm)
- **Workspace:** story-industries
- **Team:** STO (Story-industries)
- **Auth:** `~/.linear_api_token` file (personal API token, never committed)
- **Usage pattern:** `linearis issues create "title" --team "STO"`
- **Agent guide:** See `LINEARIS_AGENT_GUIDE.md` in the linearcli repo for full command reference

And add this to your global ~/.claude/CLAUDE.md under tools:

- **Linear:** Use `linearis` CLI with `~/.linear_api_token` file auth, NOT env vars

---

Token file security

• ~/.linear_api_token should have 600 permissions (owner read/write only)
• Never commit tokens to git
• Never share tokens between team members
• Each person creates their own token at linear.app/settings/api

---

License

MIT — see LICENSE.md.

Original work by Carlo Zottmann. Modifications by Francesco La Ferla.