CLI Reference

This document provides a complete reference for all IssueDB command-line interface commands and options.

Global Options

These options can be used with any command:

--db PATH: Use a custom database file instead of the default ./issuedb.sqlite
--json: Output results in JSON format for scripting and automation
--prompt: Display the LLM agent prompt guide
--ollama REQUEST: Use Ollama to convert natural language to commands
--ollama-model MODEL: Specify the Ollama model to use (default: from environment or llama3.2)
--ollama-host HOST: Ollama server host (default: localhost)
--ollama-port PORT: Ollama server port (default: 11434)

Issue Management Commands

create

Create a new issue.

issuedb-cli create -t "TITLE" [-d "DESCRIPTION"] [--priority PRIORITY] [--status STATUS] [--due-date YYYY-MM-DD] [--tag TAG1] [--tag TAG2]

Arguments:

-t, --title (required): Issue title
-d, --description: Detailed description
--priority: Priority level (low, medium, high, critical). Default: medium
--status: Initial status (open, in-progress, closed, wont-do). Default: open
--due-date: Due date in YYYY-MM-DD format
--tag: Add one or more tags (can be specified multiple times)

Examples:

# Simple issue
issuedb-cli create -t "Fix bug"

# With all options
issuedb-cli create -t "Critical security fix" -d "SQL injection" --priority critical --due-date 2025-12-31 --tag security --tag bug

# With JSON output
issuedb-cli --json create -t "New feature" --priority high

list

List issues with optional filters.

issuedb-cli list [-s STATUS] [--priority PRIORITY] [-l LIMIT] [--due-date YYYY-MM-DD] [--tag TAG]

Arguments:

-s, --status: Filter by status (open, in-progress, closed, wont-do)
--priority: Filter by priority (low, medium, high, critical)
-l, --limit: Maximum number of issues to return
--due-date: Filter by specific due date
--tag: Filter by tag name

Examples:

# List all issues
issuedb-cli list

# List open high-priority issues
issuedb-cli list -s open --priority high

# Filter by tag
issuedb-cli list --tag bug

get

Get details of a specific issue.

issuedb-cli get ID

Arguments:

ID (required): Issue ID

Examples:

issuedb-cli get 42
issuedb-cli --json get 42

update

Update an existing issue.

issuedb-cli update ID [-t "TITLE"] [-d "DESCRIPTION"] [-s STATUS] [--priority PRIORITY] [--due-date YYYY-MM-DD]

Arguments:

ID (required): Issue ID
-t, --title: New title
-d, --description: New description
-s, --status: New status (open, in-progress, closed, wont-do)
--priority: New priority (low, medium, high, critical)
--due-date: New due date (YYYY-MM-DD)

Examples:

# Update status
issuedb-cli update 1 -s in-progress

# Update due date
issuedb-cli update 1 --due-date 2025-01-01

Memory Commands

memory

Manage persistent memory for AI agents.

issuedb-cli memory COMMAND [ARGS]

Subcommands:

add: Add a memory item
list: List memory items
update: Update a memory item
delete: Delete a memory item

Examples:

# Add memory
issuedb-cli memory add "project_style" "Use PEP 8" --category "coding_standards"

# List memory
issuedb-cli memory list
issuedb-cli memory list --category coding_standards

# Update memory
issuedb-cli memory update "project_style" "Use PEP 8 and Google docstrings"

# Delete memory
issuedb-cli memory delete "project_style"

Lesson Commands

lesson

Manage lessons learned.

issuedb-cli lesson COMMAND [ARGS]

Subcommands:

add: Add a lesson learned
list: List lessons learned

Examples:

# Add lesson
issuedb-cli lesson add "Always backup before update" --issue-id 42 --category "devops"

# List lessons
issuedb-cli lesson list
issuedb-cli lesson list --category devops

Tag Commands

tag

Manage tags.

issuedb-cli tag COMMAND [ARGS]

Subcommands:

add: Add tags to an issue
remove: Remove tags from an issue
list: List all available tags

Examples:

# Add tags to issue
issuedb-cli tag add 1 bug security

# Remove tags
issuedb-cli tag remove 1 security

# List all tags
issuedb-cli tag list

Link Commands

link

Link two issues.

issuedb-cli link SOURCE_ID TARGET_ID --type TYPE

Arguments:

SOURCE_ID: ID of the source issue
TARGET_ID: ID of the target issue
--type: Relationship type (e.g., “related”, “blocks”)

Examples:

issuedb-cli link 1 2 --type related

unlink

Unlink two issues.

issuedb-cli unlink SOURCE_ID TARGET_ID [--type TYPE]

Arguments:

SOURCE_ID: ID of the source issue
TARGET_ID: ID of the target issue
--type: Optional type filter

Examples:

issuedb-cli unlink 1 2

Comment Commands

comment

Add a comment to an issue.

issuedb-cli comment ISSUE_ID -t "TEXT"

Arguments:

ISSUE_ID (required): Issue ID
-t, --text (required): Comment text

Examples:

issuedb-cli comment 1 -t "Working on this now"
issuedb-cli --json comment 1 -t "Fixed by updating config"

list-comments

List all comments for an issue.

issuedb-cli list-comments ISSUE_ID

Arguments:

ISSUE_ID (required): Issue ID

Examples:

issuedb-cli list-comments 1
issuedb-cli --json list-comments 1

delete-comment

Delete a comment.

issuedb-cli delete-comment COMMENT_ID

Arguments:

COMMENT_ID (required): Comment ID

Examples:

issuedb-cli delete-comment 5

Bulk Operations

bulk-update

Update multiple issues matching filters.

issuedb-cli bulk-update [--filter-status STATUS] [--filter-priority PRIORITY] [-s STATUS] [--priority PRIORITY]

Arguments:

--filter-status: Filter by current status
--filter-priority: Filter by current priority
-s, --status: New status to set
--priority: New priority to set

Examples:

# Close all issues
issuedb-cli bulk-update -s closed

# Close all open issues
issuedb-cli bulk-update --filter-status open -s closed

# Upgrade all medium priority to high
issuedb-cli bulk-update --filter-priority medium --priority high

bulk-create

Create multiple issues from JSON input.

issuedb-cli bulk-create [-f FILE] [-d DATA]

Arguments:

-f, --file: JSON file path
-d, --data: Inline JSON data
If neither provided, reads from stdin

JSON Format:

[
  {"title": "Issue 1", "priority": "high", "description": "Details"},
  {"title": "Issue 2", "priority": "medium"},
  {"title": "Issue 3"}
]

Examples:

# From stdin
echo '[{"title": "Issue 1"}, {"title": "Issue 2"}]' | issuedb-cli bulk-create

# From file
issuedb-cli bulk-create -f issues.json

# Inline data
issuedb-cli bulk-create -d '[{"title": "Quick issue", "priority": "low"}]'

bulk-update-json

Update multiple specific issues from JSON input.

issuedb-cli bulk-update-json [-f FILE] [-d DATA]

Arguments:

-f, --file: JSON file path
-d, --data: Inline JSON data
If neither provided, reads from stdin

JSON Format:

[
  {"id": 1, "status": "closed"},
  {"id": 2, "priority": "high", "title": "New title"},
  {"id": 3, "status": "in-progress"}
]

Examples:

echo '[{"id": 1, "status": "closed"}, {"id": 2, "priority": "high"}]' | issuedb-cli bulk-update-json

bulk-close

Close multiple issues by ID.

issuedb-cli bulk-close [-f FILE] [-d DATA]

Arguments:

-f, --file: JSON file path containing array of IDs
-d, --data: Inline JSON array of IDs
If neither provided, reads from stdin

JSON Format:

[1, 2, 3, 4, 5]

Examples:

echo '[1, 2, 3]' | issuedb-cli bulk-close
issuedb-cli bulk-close -d '[5, 7, 9]'

Reporting Commands

summary

Show aggregate statistics.

issuedb-cli summary

Examples:

issuedb-cli summary
issuedb-cli --json summary

Output includes:

Total issue count
Breakdown by status (open, in-progress, closed, wont-do - count and percentage)
Breakdown by priority (count and percentage)

report

Show detailed report of issues.

issuedb-cli report [--group-by {status,priority}]

Arguments:

--group-by: Group by status or priority. Default: status

Examples:

issuedb-cli report
issuedb-cli report --group-by priority
issuedb-cli --json report

info

Show database information and statistics.

issuedb-cli info

Examples:

issuedb-cli info
issuedb-cli --json info

audit

View audit logs.

issuedb-cli audit [-i ISSUE_ID]

Arguments:

-i, --issue-id: Filter by issue ID

Examples:

# All audit logs
issuedb-cli audit

# Logs for specific issue
issuedb-cli audit -i 1

# JSON output
issuedb-cli --json audit

Dependency Commands

block

Mark an issue as blocked by another issue.

issuedb-cli block ISSUE_ID --by BLOCKER_ID

Arguments:

ISSUE_ID (required): ID of the issue being blocked
--by (required): ID of the blocking issue

Examples:

issuedb-cli block 5 --by 3
issuedb-cli --json block 5 --by 3

unblock

Remove blocker(s) from an issue.

issuedb-cli unblock ISSUE_ID [--by BLOCKER_ID]

Arguments:

ISSUE_ID (required): ID of the blocked issue
--by: Specific blocker to remove (if omitted, removes all blockers)

Examples:

# Remove specific blocker
issuedb-cli unblock 5 --by 3

# Remove all blockers
issuedb-cli unblock 5

deps

Show dependency graph for an issue.

issuedb-cli deps ISSUE_ID

Arguments:

ISSUE_ID (required): Issue ID

Examples:

issuedb-cli deps 5
issuedb-cli --json deps 5

blocked

List all blocked issues.

issuedb-cli blocked [-s STATUS]

Arguments:

-s, --status: Filter by status

Examples:

issuedb-cli blocked
issuedb-cli --json blocked -s open

Code Reference Commands

attach

Attach a code reference to an issue.

issuedb-cli attach ISSUE_ID --file "FILE_PATH[:LINE[-END_LINE]]" [--note "NOTE"]

Arguments:

ISSUE_ID (required): Issue ID
--file (required): File path with optional line number(s)
--note: Optional note about the reference

Examples:

# Attach file
issuedb-cli attach 5 --file "src/auth.py"

# With line number
issuedb-cli attach 5 --file "src/auth.py:42"

# With line range
issuedb-cli attach 5 --file "src/auth.py:42-50"

# With note
issuedb-cli attach 5 --file "src/auth.py:42" --note "Bug location"

detach

Remove a code reference from an issue.

issuedb-cli detach ISSUE_ID --file "FILE_PATH"

Arguments:

ISSUE_ID (required): Issue ID
--file (required): File path to remove

Examples:

issuedb-cli detach 5 --file "src/auth.py"

refs

List code references for an issue.

issuedb-cli refs ISSUE_ID

Arguments:

ISSUE_ID (required): Issue ID

Examples:

issuedb-cli refs 5
issuedb-cli --json refs 5

affected

List issues that reference a specific file.

issuedb-cli affected --file "FILE_PATH"

Arguments:

--file (required): File path to search for

Examples:

issuedb-cli affected --file "src/auth.py"
issuedb-cli --json affected --file "config.py"

Time Tracking Commands

timer-start

Start tracking time on an issue.

issuedb-cli timer-start ISSUE_ID

Arguments:

ISSUE_ID (required): Issue ID

Examples:

issuedb-cli timer-start 5

timer-stop

Stop the active timer.

issuedb-cli timer-stop [ISSUE_ID]

Arguments:

ISSUE_ID: Issue ID (optional if only one timer running)

Examples:

issuedb-cli timer-stop
issuedb-cli --json timer-stop 5

timer-status

Show active timers.

issuedb-cli timer-status

Examples:

issuedb-cli timer-status
issuedb-cli --json timer-status

set-estimate

Set time estimate for an issue.

issuedb-cli set-estimate ISSUE_ID --hours HOURS

Arguments:

ISSUE_ID (required): Issue ID
--hours (required): Estimated hours

Examples:

issuedb-cli set-estimate 5 --hours 4

time-log

View time entries for an issue.

issuedb-cli time-log ISSUE_ID

Arguments:

ISSUE_ID (required): Issue ID

Examples:

issuedb-cli time-log 5
issuedb-cli --json time-log 5

time-report

Generate time reports.

issuedb-cli time-report [--period {all,week,month}] [--issue ISSUE_ID]

Arguments:

--period: Report period (all, week, month). Default: all
--issue: Filter by issue ID

Examples:

issuedb-cli time-report
issuedb-cli time-report --period week
issuedb-cli --json time-report --period month

Workspace Commands

workspace

Show workspace status.

issuedb-cli workspace

Examples:

issuedb-cli workspace
issuedb-cli --json workspace

start

Start working on an issue (sets active and starts timer).

issuedb-cli start ISSUE_ID

Arguments:

ISSUE_ID (required): Issue ID

Examples:

issuedb-cli start 5
issuedb-cli --json start 5

stop

Stop working on active issue.

issuedb-cli stop [--close]

Arguments:

--close: Also close the issue

Examples:

issuedb-cli stop
issuedb-cli stop --close
issuedb-cli --json stop

active

Show currently active issue.

issuedb-cli active

Examples:

issuedb-cli active
issuedb-cli --json active

context

Get comprehensive context for an issue (for LLM agents).

issuedb-cli context ISSUE_ID [--compact]

Arguments:

ISSUE_ID (required): Issue ID
--compact: Return minimal context

Output includes:

Issue details
Comments
Recent audit history
Related issues
Git information
Suggested actions

Examples:

issuedb-cli context 5
issuedb-cli --json context 5
issuedb-cli context 5 --compact

Duplicate Detection Commands

find-similar

Find issues similar to given text.

issuedb-cli find-similar "QUERY" [--threshold THRESHOLD] [--limit LIMIT]

Arguments:

QUERY (required): Text to search for
--threshold: Similarity threshold 0.0-1.0. Default: 0.6
--limit: Maximum results. Default: 10

Examples:

issuedb-cli find-similar "login bug"
issuedb-cli --json find-similar "authentication" --threshold 0.7

find-duplicates

Find potential duplicate groups in database.

issuedb-cli find-duplicates [--threshold THRESHOLD]

Arguments:

--threshold: Similarity threshold. Default: 0.7

Examples:

issuedb-cli find-duplicates
issuedb-cli --json find-duplicates --threshold 0.8

Template Commands

templates

List available issue templates.

issuedb-cli templates

Examples:

issuedb-cli templates
issuedb-cli --json templates

Creating from templates:

issuedb-cli create --template bug -t "Login crash" -d "App crashes"
issuedb-cli create --template feature -t "Dark mode"
issuedb-cli create --template task -t "Update deps"

Bulk Pattern Commands

bulk-close-pattern

Close issues matching a pattern.

issuedb-cli bulk-close-pattern --title "PATTERN" [--desc "PATTERN"] [--regex] [--dry-run]

Arguments:

--title: Pattern to match against title
--desc: Pattern to match against description
--regex: Treat patterns as regex (default: glob)
--dry-run: Preview without making changes

Examples:

issuedb-cli bulk-close-pattern --title "*test*"
issuedb-cli bulk-close-pattern --title "temp.*" --regex
issuedb-cli bulk-close-pattern --title "*WIP*" --dry-run

bulk-update-pattern

Update issues matching a pattern.

issuedb-cli bulk-update-pattern --title "PATTERN" [-s STATUS] [--priority PRIORITY] [--regex] [--dry-run]

Arguments:

--title: Pattern to match against title
--desc: Pattern to match against description
-s, --status: New status
--priority: New priority
--regex: Treat patterns as regex
--dry-run: Preview without making changes

Examples:

issuedb-cli bulk-update-pattern --title "*bug*" --priority high
issuedb-cli bulk-update-pattern --title ".*urgent.*" --regex -s in-progress

bulk-delete-pattern

Delete issues matching a pattern.

issuedb-cli bulk-delete-pattern --title "PATTERN" --confirm [--regex] [--dry-run]

Arguments:

--title: Pattern to match against title
--desc: Pattern to match against description
--confirm: Required unless using –dry-run
--regex: Treat patterns as regex
--dry-run: Preview without making changes

Examples:

issuedb-cli bulk-delete-pattern --title "*temp*" --confirm
issuedb-cli bulk-delete-pattern --title "test.*" --regex --dry-run

Administrative Commands

clear

Clear all issues from the database. Requires confirmation.

issuedb-cli clear --confirm

Arguments:

--confirm (required): Safety flag to prevent accidental deletion

Warning

This permanently deletes all issues. The audit log is preserved.

Examples:

issuedb-cli clear --confirm

Exit Codes

IssueDB uses the following exit codes:

0: Success
1: Error (invalid arguments, issue not found, etc.)

Errors are printed to stderr, and successful output is printed to stdout.