CLI Reference

The issy CLI is your primary interface for managing issues from the terminal. All commands work with the .issy/issues/ directory in your project.

Commands

`issy`

Launch the web UI at http://localhost:1554 for browsing issues in the browser.

issy

`issy init`

Create the .issy/issues/ directory structure.

issy init              # Create empty directory
issy init --seed       # Create with a welcome issue

`issy list`

List issues in roadmap order (default).

issy list                     # Open issues only
issy list --all               # Include closed issues
issy list --unblocked         # Open issues with no open blockers
issy list --priority high     # Filter by priority
issy list --scope small       # Filter by scope
issy list --type bug          # Filter by type
issy list --search "keyword"  # Fuzzy search
issy list --sort priority     # Sort by priority
issy list --sort created      # Sort by creation date
issy list --sort id           # Sort by ID

Filters:

Flag	Values
`--unblocked`	Open issues with no open blockers
`--priority`	`high`, `medium`, `low`
`--scope`	`small`, `medium`, `large`
`--type`	`bug`, `improvement`

The list output includes a compact Blk column. - means the issue is unblocked; otherwise the value is the number of currently open blockers.

Sort options:

Value	Description
`roadmap`	Roadmap order (default)
`priority`	By priority level
`created`	By creation date
`updated`	By last update
`id`	By issue ID

`issy next`

Show the next issue to work on (first open issue in roadmap order).

issy next

`issy learn`

Print AI-agent instructions for the installed issy version.

issy learn

`issy search`

Fuzzy search across issue titles and content.

issy search "dashboard"        # Search open issues
issy search "k8s" --all        # Include closed issues

`issy read`

View the full contents of an issue.

issy read 0001

`issy create`

Create a new issue. When other open issues exist, you must specify a position.

issy create --title "Fix login bug" --type bug --priority high --after 0002
issy create --title "Add dark mode" --type improvement --last --labels "ui, frontend"
issy create --title "Add export" --depends-on 0001,0002 --last
issy create --title "Urgent fix" --first
issy create --title "Fix crash" --body "## Problem\n\nApp crashes on startup." --last

Required flags:

Flag	Description
`--title`	Issue title

Optional flags:

Flag	Description
`--type`	`bug` or `improvement`
`--priority`	`high`, `medium`, or `low`
`--scope`	`small`, `medium`, or `large`
`--labels`	Comma-separated labels
`--depends-on`	Comma-separated blocking issue IDs
`--body`	Issue body content (markdown)

Position flags (required when open issues exist):

Flag	Description
`--before <id>`	Insert before issue
`--after <id>`	Insert after issue
`--first`	Insert at beginning
`--last`	Insert at end

If --depends-on names an open issue, the new issue must be placed after that blocker. issy create fails if the requested position would make the new issue appear before an open dependency.

`issy update`

Update an existing issue’s properties.

issy update 0001 --priority low
issy update 0001 --after 0003          # Reposition in roadmap
issy update 0001 --first               # Move to top
issy update 0001 --labels "api, backend"
issy update 0001 --depends-on 0002,0003
issy update 0001 --body "New details"  # Replace body content

Dependency order is also enforced when updating. Adding --depends-on, changing position, or reopening an issue fails if the resulting roadmap would place an open blocked issue before one of its open blockers.

`issy close`

Close an issue.

issy close 0001

`issy reopen`

Reopen a closed issue. Position flags are required when other open issues exist.

issy reopen 0001 --last
issy reopen 0001 --after 0004

`issy skill install`

Install the lightweight bootstrap skill for assistants that support skills.

issy skill install

The skill tells compatible agents when to run issy learn; the detailed agent reference lives in the CLI output.

`issy migrate`

Migrate from .issues/ (v0.4.x format) to .issy/.

issy migrate

`issy help`

Show help information.

issy help

`issy --version`

Display the installed version.

issy --version