CLI API

The CLI module provides both the command-line interface and a Python API for programmatic access.

CLI Class

class issuedb.cli.CLI(db_path: str | None = None)[source]

Command-line interface for IssueDB.

Parameters:: db_path – Optional path to database file

Example:

from issuedb.cli import CLI

cli = CLI()  # Use default database
cli = CLI("/path/to/custom.db")  # Use custom database

Returns:: Formatted output string

CLI.memory_add(key: str, value: str, category: str = 'general', as_json: bool = False) → str[source]

Add a memory item.

Parameters:

key – Unique key for the memory item
value – Value/content of the memory
category – Category grouping
as_json – Return JSON output

Returns:

Formatted output string

CLI.memory_list(category: str | None = None, search: str | None = None, as_json: bool = False) → str[source]

List memory items.

Parameters:

category – Filter by category
search – Search term for key/value
as_json – Return JSON output

Returns:

Formatted output string

CLI.memory_update(key: str, value: str | None = None, category: str | None = None, as_json: bool = False) → str[source]

Update a memory item.

Parameters:

key – Key of the item to update
value – New value
category – New category
as_json – Return JSON output

Returns:

Formatted output string

CLI.memory_delete(key: str, as_json: bool = False) → str[source]

Delete a memory item.

Parameters:

key – Key of the item to delete
as_json – Return JSON output

Returns:

Formatted output string

CLI.lesson_add(lesson: str, issue_id: int | None = None, category: str = 'general', as_json: bool = False) → str[source]

Add a lesson learned.

Parameters:

lesson – The lesson text
issue_id – Related issue ID
category – Category grouping
as_json – Return JSON output

Returns:

Formatted output string

CLI.lesson_list(issue_id: int | None = None, category: str | None = None, as_json: bool = False) → str[source]

List lessons learned.

Parameters:

issue_id – Filter by related issue
category – Filter by category
as_json – Return JSON output

Returns:

Formatted output string

CLI.tag_issue(issue_id: int, tags: list[str], as_json: bool = False) → str[source]

Add tags to an issue.

Parameters:

issue_id – Issue ID
tags – List of tags to add
as_json – Return JSON output

Returns:

Formatted output string

CLI.untag_issue(issue_id: int, tags: list[str], as_json: bool = False) → str[source]

Remove tags from an issue.

Parameters:

issue_id – Issue ID
tags – List of tags to remove
as_json – Return JSON output

Returns:

Formatted output string

CLI.tag_list(as_json: bool = False) → str[source]

List all available tags.

Parameters:: as_json – Return JSON output
Returns:: Formatted output string

CLI.link_issues(source: int, target: int, type: str, as_json: bool = False) → str[source]

Link two issues together.

Parameters:

source – Source issue ID
target – Target issue ID
type – Relationship type (e.g., “related”, “blocks”)
as_json – Return JSON output

Returns:

Formatted output string

CLI.unlink_issues(source: int, target: int, type: str | None = None, as_json: bool = False) → str[source]

Unlink issues.

Parameters:

source – Source issue ID
target – Target issue ID
type – Optional relationship type filter
as_json – Return JSON output

Returns:

Formatted output string

Issue Methods

CLI.create_issue(title: str, description: str | None = None, priority: str = 'medium', status: str = 'open', due_date: str | None = None, as_json: bool = False, force: bool = False, check_duplicates: bool = False) → str[source]

Create a new issue.

Parameters:

title – Issue title
description – Issue description
priority – Priority level
status – Initial status
due_date – Due date (YYYY-MM-DD)
as_json – Return JSON output
force – Force creation even if duplicates found
check_duplicates – Enable duplicate checking

Returns:

Formatted output string

Example:

output = cli.create_issue(
    "Fix bug",
    description="Details here",
    priority="high",
    due_date="2025-12-31"
)
print(output)

# JSON output
json_output = cli.create_issue("Fix bug", as_json=True)

List issues with optional filters.

Parameters:

status – Filter by status
priority – Filter by priority
limit – Maximum results
due_date – Filter by due date
tag – Filter by tag
as_json – Return JSON output

Returns:

Formatted output string

CLI.get_issue(issue_id: int, as_json: bool = False) → str[source]

Get details of a specific issue.

Parameters:

issue_id – Issue ID
as_json – Return JSON output

Returns:

Formatted output string

Raises:

ValueError – If issue not found

CLI.update_issue(issue_id: int, as_json: bool = False, **updates) → str[source]

Update an issue.

Parameters:

issue_id – Issue ID
as_json – Return JSON output
updates – Fields to update (title, description, priority, status, due_date)

Returns:

Formatted output string

Raises:

ValueError – If issue not found

Example:

cli.update_issue(1, status="closed", priority="low", due_date="2025-01-01")

Comment Methods

CLI.add_comment(issue_id: int, text: str, as_json: bool = False) → str[source]

Add a comment to an issue.

Parameters:

issue_id – Issue ID
text – Comment text
as_json – Return JSON output

Returns:

Formatted output string

Raises:

ValueError – If issue not found or text empty

Example:

cli.add_comment(1, "Working on this now")

CLI.list_comments(issue_id: int, as_json: bool = False) → str[source]

List all comments for an issue.

Parameters:

issue_id – Issue ID
as_json – Return JSON output

Returns:

Formatted output string

CLI.delete_comment(comment_id: int, as_json: bool = False) → str[source]

Delete a comment.

Parameters:

comment_id – Comment ID
as_json – Return JSON output

Returns:

Formatted output string

Raises:

ValueError – If comment not found

Bulk Methods

CLI.bulk_create(json_input: str, as_json: bool = False) → str[source]

Bulk create issues from JSON.

Parameters:

json_input – JSON string containing list of issues
as_json – Return JSON output

Returns:

Formatted output string

Raises:

ValueError – If JSON invalid

Example:

json_data = '[{"title": "Issue 1"}, {"title": "Issue 2"}]'
output = cli.bulk_create(json_data, as_json=True)

CLI.bulk_update_json(json_input: str, as_json: bool = False) → str[source]

Bulk update issues from JSON.

Parameters:

json_input – JSON string with list of updates
as_json – Return JSON output

Returns:

Formatted output string

CLI.bulk_close(json_input: str, as_json: bool = False) → str[source]

Bulk close issues from JSON.

Parameters:

json_input – JSON string with list of issue IDs
as_json – Return JSON output

Returns:

Formatted output string

Reporting Methods

CLI.get_summary(as_json: bool = False) → str[source]

Get aggregate statistics.

Parameters:: as_json – Return JSON output
Returns:: Formatted output string

CLI.get_report(group_by: str = 'status', as_json: bool = False) → str[source]

Get detailed report.

Parameters:

group_by – “status” or “priority”
as_json – Return JSON output

Returns:

Formatted output string

CLI.get_info(as_json: bool = False) → str[source]

Get database information.

Parameters:: as_json – Return JSON output
Returns:: Formatted output string

CLI.get_audit_logs(issue_id: int | None = None, as_json: bool = False) → str[source]

Get audit logs.

Parameters:

issue_id – Optional filter by issue
as_json – Return JSON output

Returns:

Formatted output string

Administrative Methods

CLI.clear_all(confirm: bool = False, as_json: bool = False) → str[source]

Clear all issues.

Parameters:

confirm – Must be True to proceed
as_json – Return JSON output

Returns:

Formatted output string

Raises:

ValueError – If confirm is False

Utility Methods

CLI.format_output(data, as_json: bool = False) → str[source]

Format data for output.

Parameters:

data – Data to format (Issue, list, dict, etc.)
as_json – Return JSON format

Returns:

Formatted string

Main Function

issuedb.cli.main()[source]

Main entry point for the CLI application.

This is called when running issuedb-cli from the command line.

Example:

from issuedb.cli import main

# Run CLI (typically not called directly)
main()

Usage Example

Using CLI class programmatically:

from issuedb.cli import CLI
import json

# Initialize
cli = CLI("./project.db")

# Create an issue
result = cli.create_issue("New feature", priority="high", as_json=True)
issue = json.loads(result)
print(f"Created issue #{issue['id']}")

# Add comment
cli.add_comment(issue['id'], "Started working on this")

# Update status
cli.update_issue(issue['id'], status="in-progress")

# Get summary
summary = json.loads(cli.get_summary(as_json=True))
print(f"Total issues: {summary['total_issues']}")

# List all issues
issues = json.loads(cli.list_issues(as_json=True))
for i in issues:
    print(f"#{i['id']}: {i['title']} [{i['status']}]")

# Close with comment
cli.update_issue(issue['id'], status="closed")
cli.add_comment(issue['id'], "Completed and deployed")