isq CLI

A CLI for GitHub, Linear, and JIRA issues. Instant. Offline-first.

Installation

Before using any isq commands, verify isq is installed:

isq --version

If the command fails or isq is not found, install it:

curl -LsSf https://cameronwestland.com/isq/install.sh | sh

After installation, verify it succeeded by running isq --version again.

Note: macOS and Linux only. Windows is not supported.

Why isq is Fast

isq syncs issues to a local SQLite database. All reads come from this cache—no network round-trip. A background daemon keeps the cache fresh automatically.

CLI reads → Local SQLite (instant, <1ms)
CLI writes → API directly (then cached)
Daemon → Syncs in background every 15s

Core Commands

Link a Repository

Before using isq, link your repo to GitHub, Linear, or JIRA:

isq link github    # Link current repo to GitHub Issues
isq link linear    # Link current repo to Linear (current auth context)
isq link linear -o list-teams          # List teams in current Linear auth context
isq link linear -o team=ENG            # Link specific Linear team
isq link linear -o reauth -o team=ENG  # Force fresh Linear auth for this repo
isq link jira      # Link current repo to JIRA Cloud

For JIRA, you can also use options to select a specific project:

isq link jira -o list-projects   # List available JIRA projects
isq link jira -o project=MYPROJ  # Link to specific project

Linear multi-workspace/account note:

• Credentials are repo-scoped for Linear.
• Use -o reauth when a repo must bind to a different Linear account/workspace than another repo.

Linking also installs a git commit hook that auto-appends issue references to commits.

Sync Issues

Manually sync issues from the remote:

isq sync

The daemon also syncs automatically in the background.

List Issues

isq issue list                          # All issues (sorted by priority)
isq issue list --state=open             # Open issues only
isq issue list --state=closed           # Closed issues only
isq issue list --label=bug              # Filter by label
isq issue list --mine                   # Issues assigned to me
isq issue list --unassigned             # Issues with no assignee
isq issue list --goal "v1"              # Issues in a goal/milestone
isq issue list --id 7,12,45             # Filter by specific issue IDs
isq issue list --sort newest            # Sort by issue number (newest first)
isq issue list --sort updated           # Sort by last updated
isq issue list --label=bug --state=open # Combine filters
isq issue list --json                   # JSON output
isq issue list --tree                   # Show as parent-child hierarchy
isq issue list --root-only              # Only top-level issues (no parents)
isq issue list --children-of 42         # Children of issue #42 for scripts

Note: --id gives a compact list view of specific issues. Use isq issue show <id> for full details including description and comments.

Show Issue Details

isq issue show 423        # Show issue #423
isq issue show 423 --json # JSON output

Create Issues

isq issue create --title "Fix login bug"
isq issue create --title "Add feature" --body "Description here"
isq issue create --title "Bug" --label=bug

Edit Issue Fields

isq issue edit 423 --title "Refined issue title"
isq issue edit 423 --body "Updated description"
cat summary.md | isq issue edit 423 --body -
isq issue edit 423 --priority 2
isq issue update 423 --title "..."   # Alias for edit

Priority scale:

• 0 urgent
• 1 high
• 2 medium
• 3 low
• 4 none

Forge notes:

• Linear supports priority updates directly.
• JIRA supports priority updates for 0..3 (no explicit none equivalent).
• GitHub has no native issue priority update via API; use labels/config mapping.

Comment on Issues

isq issue comment 423 "Fixed in commit abc123"

Close and Reopen

isq issue close 423
isq issue reopen 423

Manage Labels

isq issue label 423 add bug
isq issue label 423 remove bug

Assign Users

isq issue assign 423 username

Label Commands

List and create repository labels (for discovery and priority setup):

isq label list                              # List all repo labels
isq label list --json                       # JSON output
isq label create P0 --color ff0000          # Create a label
isq label create P1 --color orange --description "High priority"

Development Workflow

isq integrates with git worktrees so your filesystem becomes your context. Each worktree is associated with an issue—no need to track issue IDs manually.

Start Working on an Issue

isq start 891

This command:

1. Creates a git worktree at ~/src/myapp-891-fix-auth-timeout
2. Creates a branch named 891-fix-auth-timeout
3. Marks the issue as in-progress (adds labels on GitHub, transitions state on Linear)
4. Runs any setup script defined in .config/isq.toml

Show Current Issue

isq              # Show current issue with full details
isq current      # Just the issue number (for scripts)
isq current -q   # Quiet mode: no output if no issue, exit code 1

When in a worktree, isq (no args) shows the associated issue:

#891 Auth timeout on slow connections                        open
───────────────────────────────────────────────────────────────────
Connections time out after 30s on slow networks...

Branch: 891-fix-auth-timeout
Worktree: ~/src/myapp-891-fix-auth-timeout

Automatic Commit References

When you commit in a worktree with an associated issue, the commit message automatically gets the issue reference appended:

git commit -m "Fix connection pool sizing"
# Becomes: "Fix connection pool sizing [#891]"

Clean Up

When done with an issue (PR merged, etc.):

isq cleanup         # Remove worktree, clear association, and clean up issue state
isq cleanup --keep  # Keep worktree directory, just clear association

Cleanup undoes what isq start did:

• GitHub: Removes labels added on start (e.g., "in progress")
• Linear/JIRA: Can transition issue back to a state (e.g., "backlog")

Configure in .config/isq.toml:

[on_cleanup]
remove_labels = ["in progress"]  # GitHub
# transition = "backlog"         # Linear/JIRA

Goal Commands

Goals are time-bound containers for issues. They map to GitHub Milestones and Linear Projects.

List Goals

isq goal list                 # Open goals (default)
isq goal list --state=closed  # Closed goals
isq goal list --state=all     # All goals
isq goal list --json          # JSON output

Show Goal Details

isq goal show "v1"        # Show goal by name
isq goal show "v1" --json # JSON output

Create Goals

isq goal create "v1"
isq goal create "v1" --target 2026-02-01
isq goal create "v1" --target 2026-02-01 --body "First public release"

Assign Issues to Goals

isq goal assign 423 "v1"  # Assign issue #423 to goal "v1"

Close Goals

isq goal close "v1"

Daemon Commands

The daemon syncs issues in the background and enables instant reads.

isq daemon start    # Start the background daemon
isq daemon stop     # Stop the daemon
isq daemon status   # Check daemon status and watched repos

Diagnostics and Updates

isq doctor            # Diagnose common issues and suggest fixes
isq doctor --verbose  # Show detailed diagnostics
isq doctor --check auth  # Run specific check (auth, repo, sync, service, database, network)

isq update check      # Check if a newer version is available
isq update install    # Download and install the latest version

Other Commands

isq status        # Show auth, sync health, and daemon status
isq unlink        # Remove link and commit hook from current repo
isq logout github # Remove stored credentials for a forge

Offline Support

When offline, write operations queue locally and sync when back online:

# Works offline - queues the operation
isq issue create --title "New issue"
# Output: ✓ Queued: New issue (offline, 8ms)

# When back online, daemon syncs automatically
isq daemon status
# Output: ✓ Synced 2 pending operations

JSON Output

All commands support --json for machine-readable output. Use this for scripts and AI agent workflows:

isq issue list --json
isq issue show 423 --json
isq issue create --title "Bug" --json
isq status --json

Views (Saved Filters)

Views are named filter combinations that save you from typing repetitive flags. They're stored in your user config (~/.config/isq/config.toml) and work across all repositories.

Create a View

# Create a view for high-priority bugs assigned to me
isq view create my-bugs --label=bug --state=open --mine --priority-lte=2

# Create a view for stale unassigned issues
isq view create stale --unassigned --updated-before="30 days"

# Create a view for backlog triage
isq view create triage --state=open --unassigned --label-not=wontfix

Use a View

Reference views with @ prefix in issue list:

isq issue list @my-bugs      # Expands to: --label=bug --state=open --mine --priority-lte=2
isq issue list @stale        # Expands to: --unassigned --updated-before="30 days"
isq issue list @triage       # Expands to: --state=open --unassigned --label-not=wontfix

Views can be combined with additional flags (CLI flags override view settings):

isq issue list @my-bugs --label=security  # Overrides label from view
isq issue list @triage --json             # Adds json output

Manage Views

isq view list             # List all views
isq view show my-bugs     # Show view details
isq view delete stale     # Delete a view

Available View Filters

User Defaults

You can also set default JSON output mode in your config:

# ~/.config/isq/config.toml
[defaults]
json = true    # All commands output JSON by default

Command Reference

Guidance

• Prefer the CLI for all issue operations rather than calling GitHub/Linear APIs directly
• Use isq start when beginning work on an issue—it sets up the worktree and tracks context automatically
• NEVER manually create branches with git checkout -b when starting issue work—always use isq start <id> instead, then cd into the created worktree
• NEVER remove or clean up worktrees created by isq start—they are the intended working environment
• Use --json when you need structured output for further processing
• Reads are instant because they come from the local cache—no need to worry about API rate limits for queries
• Writes go directly to the API when online, or queue locally when offline
• The daemon is optional but recommended—it keeps the cache fresh automatically

Common Workflows

Initial Setup

cd /path/to/your/repo
isq link github      # or: isq link linear, isq link jira
# For different Linear workspace/account per repo:
# isq link linear -o reauth -o team=ENG
isq sync             # Initial sync
isq daemon start     # Start background sync

Feature Development

# Find an issue to work on
isq issue list --state=open --label=feature

# Start working (creates worktree, branch, marks in-progress)
isq start 891

# Work on the feature...
# Commits auto-reference the issue: "Add feature [#891]"

# When done, clean up
isq cleanup

Daily Issue Triage

isq issue list --state=open --label=bug
isq issue show 423
isq issue comment 423 "Looking into this"
isq issue close 423

Working Offline

# On a plane, no internet
isq issue list                    # Works! Reads from cache
isq issue create --title "Idea"   # Queues locally

# Back online
isq daemon status                 # Shows pending ops synced

Finding What to Work On

When users ask "what should I work on?" or similar, use these patterns.

Understanding Priority

Issues have priority levels (shown in JSON output):

• 0 / urgent — Drop everything, fix now
• 1 / high — Important, do soon
• 2 / medium — Normal priority
• 3 / low — Nice to have
• 4 / none — No priority set

Issues are sorted by priority by default. Always recommend highest priority first.

Linear: Priority is native (works out of box).

GitHub: Priority requires explicit [priority] config in .config/isq.toml:

[priority]
P0 = 0  # urgent
P1 = 1  # high
bug = 1 # treat bugs as high priority
P2 = 2  # medium
P3 = 3  # low

Pre-assigned Teams

If issues are assigned during sprint planning, find the user's top priority work:

isq issue list --mine --json

Recommend the highest priority assigned issue.

Pull-from-Backlog Teams

If the team pulls from a shared backlog:

isq issue list --goal "Sprint 5" --unassigned --json

Recommend the highest priority unassigned issue, then assign and start:

isq issue assign 42 username
isq start 42

Not Sure Which Model?

Ask: "Does your team pre-assign issues, or do you pull from a shared backlog?"

Example Workflow: "What Should I Work On?"

# Pre-assigned model
isq issue list --mine --json
# Look at top result (highest priority)
# Recommend it to user
isq start <id>

# Pull model
isq issue list --goal "Current Sprint" --unassigned --json
# Look at top result
# Recommend it, then:
isq issue assign <id> <username>
isq start <id>

Setting Up Priority (GitHub)

If priority labels aren't configured for a GitHub repo:

1. Check existing labels: isq label list
2. Either map existing labels to priorities in .config/isq.toml
3. Or create priority labels: isq label create P0 --color ff0000

Example configuration:

# .config/isq.toml
[priority]
P0 = 0
P1 = 1
bug = 1
P2 = 2
P3 = 3

Troubleshooting

General Diagnosis

isq doctor            # Check auth, repo, sync, service, database, network
isq doctor --verbose  # Show detailed diagnostics

Daemon Not Starting

isq daemon status
# If stuck on macOS:
launchctl stop com.isq.daemon
isq daemon start

Stale Cache

isq sync    # Force manual sync

Check What's Linked

isq status