IssueLoop CLI — all subcommands, flags, and output

This page is the complete reference for every issueloop CLI subcommand, extracted directly from the argparse definitions in cli.py. Each entry shows the full usage line, all accepted arguments and flags with their types and defaults, and the exact output format the command prints to stdout.

check-env

issueloop check-env

Verifies that your environment is ready to run IssueLoop. The check covers three areas in order:

Core Python packages — requests, yaml, and pathspec must be importable.
Database backend — for local (SQLite) no extra check is needed; for supabase, SUPABASE_URL and SUPABASE_KEY must be set and the supabase Python package must be installed.
LLM provider — for ollama, the binary must be on PATH, the server must be responding at http://localhost:11434, and the required model (qwen2.5-coder:7b) must be pulled. For anthropic or openai, an api_key must be configured.

No arguments or flags. Each check line is prefixed with [PASS], [WARN], or [FAIL]. A FAIL on a blocking check means IssueLoop will not operate correctly.

$ issueloop check-env
[PASS] python package: requests
[PASS] python package: yaml
[PASS] python package: pathspec
[PASS] database backend: local (sqlite) — no external service required
[PASS]  ollama binary on PATH
[PASS]  ollama server responding
[PASS]  model pulled: qwen2.5-coder:7b

ALL BLOCKING CHECKS PASSED

If you have configured multiple LLM providers via llm={"providers": [...]}, check-env checks each provider in priority order and reports [WARN] (not [FAIL]) for individual providers, then confirms whether at least one is ready.

scan

issueloop scan <repo_path>

Walks the directory tree at repo_path, classifies files by language, and writes a JSON inventory to data/logs/<repo_name>_files.json. Subsequent test and tickets runs use this inventory to identify which files are relevant to a failure. Arguments

Name	Type	Required	Description
`repo_path`	string (path)	✅ Yes	Path to the repository root to scan

Example

$ issueloop scan repos/myrepo
scanned 87 files — {'python': 62, 'yaml': 8, 'markdown': 12, 'other': 5}

The printed summary shows the total file count and a breakdown by detected language. The full inventory (with individual file paths) is written to the JSON file — pass repo_path as an absolute or relative path; IssueLoop resolves it automatically.

test

issueloop test <repo_name>

Reads data/test_manifest.json for the entry matching repo_name, runs each configured test command in a subprocess, and writes the combined stdout+stderr output to the log cache. Failing runs are what tickets later reads to generate tickets. Arguments

Name	Type	Required	Description
`repo_name`	string	✅ Yes	Name matching an entry in `test_manifest.json`

Example

$ issueloop test myrepo
[OK]   unit (exit 0)
[FAIL] integration (exit 1)
[OK]   lint (exit 0)

One line is printed per test defined in the manifest. [OK] means exit code 0; [FAIL] means any non-zero exit code. The raw log output is written to disk regardless of exit code so the LLM triage step has full context.

tickets

issueloop tickets <repo_name>

Reads the log cache written by test and calls the LLM to split each failing run into one or more independent tickets. Each ticket gets an LLM-assigned priority (critical, high, medium, or low) and a short error summary. The tickets are stored in the configured database (local SQLite by default). Arguments

Name	Type	Required	Description
`repo_name`	string	✅ Yes	Name matching a previously-tested repo

Example

$ issueloop tickets myrepo
created 3 ticket(s)
  [high] AssertionError in test_auth.py::test_login — expected 200 got 401
  [high] TypeError: unsupported operand type(s) for +: 'int' and 'str' (utils.py:42)
  [medium] DeprecationWarning treated as error in test_config.py

One summary line is printed per created ticket, indented, with the priority in brackets followed by the error_summary the LLM generated.

issueloop next <repo_name>

Atomically claims the highest-priority pending ticket (sets its status to in_progress and records a dispensed_at timestamp), then prints it as formatted JSON. If no pending tickets exist, prints a plain message instead. Designed to be called by an agent loop: call next, fix the issue, then call resolve or fail before calling next again. Arguments

Name	Type	Required	Description
`repo_name`	string	✅ Yes	The repo whose ticket queue to drain

Example — ticket available

$ issueloop next myrepo
{
  "id": "a3f9c1b2-...",
  "repo": "myrepo",
  "priority": "high",
  "status": "in_progress",
  "error_summary": "AssertionError in test_auth.py::test_login — expected 200 got 401",
  "raw_log_ref": "data/logs/myrepo_integration.log",
  "command": "pytest tests/test_auth.py",
  "test_id": "integration",
  "attempts": 0,
  "escalation_summary": null,
  "proposed_fix": null,
  "created_at": "2025-01-15 10:32:01.482910",
  "resolved_at": null,
  "dispensed_at": "2025-01-15 11:04:22.019847"
}

Example — queue empty

$ issueloop next myrepo
no pending tickets

Pipe the JSON output through jq to extract specific fields: issueloop next myrepo | jq '.id'

watch

issueloop watch <repo_name> --command "<cmd>" [--cwd <path>] [--debounce <seconds>]
issueloop watch <repo_name> --log-file <path> [--debounce <seconds>]

Runs in the foreground and monitors for runtime errors in one of two modes. Mode A (--command) spawns the given shell command as a child process and captures its output. Mode B (--log-file) tails an existing log file written by an already-running process. Detected errors are debounced — a burst of output is collected until --debounce seconds of silence passes, then the entire block is flushed as a single log entry. That entry lands in the same log format as the batch test runner, so issueloop tickets picks it up with no extra steps. Press Ctrl+C to stop watching. Arguments

Name	Type	Required	Description
`repo_name`	string	✅ Yes	The repo to associate captured errors with
`--command`	string	Mode A	Shell command to spawn and own
`--log-file`	string	Mode B	Path to an existing log file to tail
`--cwd`	string (path)	No	Working directory for `--command` (Mode A only)
`--debounce`	float	No	Seconds of quiet before flushing a detected error block (default: `3.0`)

--command and --log-file are mutually exclusive. Specifying both, or neither, is an error. Examples

# Mode A — spawn a process and watch its output
issueloop watch myrepo --command "python3 main.py" --cwd repos/myrepo --debounce 5.0

# Mode B — tail a log file from an external process
issueloop watch myrepo --log-file /var/log/myapp/app.log --debounce 3.0

Terminal output (Mode A)

$ issueloop watch myrepo --command "python3 main.py" --cwd repos/myrepo
watching process for 'myrepo': python3 main.py  (Ctrl+C to stop)

Terminal output (Mode B)

$ issueloop watch myrepo --log-file /var/log/myapp/app.log
watching log file for 'myrepo': /var/log/myapp/app.log  (Ctrl+C to stop)

When you press Ctrl+C, the watcher shuts down cleanly:

^C
stopping watcher...

serve

issueloop serve [--port <port>]

Starts the local HTTP bridge, binding a small JSON API to 127.0.0.1 on the given port. This lets non-Python callers (Node, Go, shell scripts, etc.) interact with the ticket queue over HTTP without importing the Python library. See HTTP Endpoints for the full endpoint reference. Arguments

Name	Type	Required	Description
`--port`	int	No	Port to listen on (default: `8787`)

Example

$ issueloop serve --port 8787
issueloop serving on http://127.0.0.1:8787  (Ctrl+C to stop)

Press Ctrl+C to stop the server:

^C
stopped

The server binds to 127.0.0.1 only. It has no authentication layer and is intended for local use. Do not expose it to external networks without placing your own gateway in front of it.

cleanup

issueloop cleanup [--days <n>] [--repo <name>]

Deletes tickets whose status is done or failed and whose created_at timestamp is older than the threshold. If --days is omitted, the threshold falls back to retention_days from your IssueLoop config (default 30). Use --repo to limit deletion to a single repo. Arguments

Name	Type	Required	Description
`--days`	int	No	Delete tickets older than N days (default: `retention_days` from config)
`--repo`	string	No	Limit deletion to a specific repo name

Examples

# Remove all old done/failed tickets across all repos using the configured retention window
issueloop cleanup

# Override the retention window to 7 days for all repos
issueloop cleanup --days 7

# Clean up only the myrepo queue, older than 14 days
issueloop cleanup --days 14 --repo myrepo

Output

$ issueloop cleanup --days 30
removed 12 old ticket(s)

Python API

CLI Reference

HTTP Server

IssueLoop CLI — all subcommands, flags, and output

check-env

scan

test

tickets

next

watch

serve

cleanup

Build docs developers (and LLMs) love

Python API

CLI Reference

HTTP Server

Documentation Index

​check-env

​scan

​test

​tickets

​next

​watch

​serve

​cleanup

Build docs developers (and LLMs) love

check-env

scan

test

tickets

next

watch

serve

cleanup