Add --json flag to tq CLI for programmatic queue inspection #9
Conversation
Enable agents and status lines to read task queue state by adding structured JSON output to list, logs, and clear commands. The command field is now stored in the queue table and included in JSON output, allowing consumers to see what's actually running (e.g., "./gradlew build"). Changes: - Add --json flag to tq list, logs, and clear subcommands - Add command column to queue schema with migration for existing DBs - Add TestJsonSchemaContracts test class to enforce JSON structure stability - JSON mode for clear skips interactive confirmation (implies --force) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds structured JSON output options to the tq CLI to support programmatic inspection of queue state, and extends the queue DB schema to store the task command.
Changes:
- Add
--jsonoutput mode totq list,tq logs, andtq clear. - Persist the task
commandin thequeuetable and add a migration for existing DBs. - Add JSON schema contract tests to enforce stable output shape for consumers.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
tq.py |
Adds --json flags for list/logs/clear, emits JSON payloads, and stores the command string when registering tasks. |
queue_core.py |
Extends the queue table schema with a command column and adds a migration to retrofit existing DBs. |
tests/test_tq_cli.py |
Adds functional + contract tests asserting exact JSON schemas for list, logs, and clear. |
Comments suppressed due to low confidence (8)
tests/test_tq_cli.py:505
- This import of module os is redundant, as it was previously imported on line 7.
import os
tests/test_tq_cli.py:506
- This import of module signal is redundant, as it was previously imported on line 8.
import signal
tests/test_tq_cli.py:574
- This import of module os is redundant, as it was previously imported on line 7.
import os
tests/test_tq_cli.py:575
- This import of module signal is redundant, as it was previously imported on line 8.
import signal
tests/test_tq_cli.py:632
- This import of module os is redundant, as it was previously imported on line 7.
import os
tests/test_tq_cli.py:633
- This import of module signal is redundant, as it was previously imported on line 8.
import signal
tests/test_tq_cli.py:703
- This import of module signal is redundant, as it was previously imported on line 8.
import signal
tests/test_tq_cli.py:740
- This import of module signal is redundant, as it was previously imported on line 8.
import signal
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
tq.py
Outdated
| # clear | ||
| subparsers.add_parser("clear", help="Clear all tasks from queue") | ||
| clear_parser = subparsers.add_parser("clear", help="Clear all tasks from queue") | ||
| clear_parser.add_argument("--json", action="store_true", help="Output in JSON format (implies --force)") |
There was a problem hiding this comment.
The --json help text says it "implies --force", but there is no --force/--yes option implemented for tq clear. This is confusing for users and makes the help output inaccurate. Either add a real --force flag (and keep --json implying it), or update the help text to say that --json skips confirmation.
| clear_parser.add_argument("--json", action="store_true", help="Output in JSON format (implies --force)") | |
| clear_parser.add_argument( | |
| "--json", | |
| action="store_true", | |
| help="Output in JSON format and skip confirmation", | |
| ) |
| def test_list_json_empty_queue(self, temp_data_dir): | ||
| """Test list --json command with empty queue.""" | ||
| result = run_tq("list", "--json", data_dir=temp_data_dir) | ||
|
|
||
| assert result.returncode == 0 | ||
| output = json.loads(result.stdout) | ||
| assert output == { | ||
| "tasks": [], | ||
| "summary": {"total": 0, "running": 0, "waiting": 0} | ||
| } | ||
|
|
||
| def test_list_json_no_database(self, temp_data_dir): | ||
| """Test list --json command when database doesn't exist.""" | ||
| result = run_tq("list", "--json", data_dir=temp_data_dir) | ||
|
|
||
| assert result.returncode == 0 | ||
| output = json.loads(result.stdout) | ||
| assert output["tasks"] == [] | ||
| assert output["summary"]["total"] == 0 |
There was a problem hiding this comment.
test_list_json_empty_queue and test_list_json_no_database currently exercise the same code path (both run against a fresh temp dir with no DB file). This duplicates coverage and the "empty_queue" name/docstring is misleading. Consider removing one test, or change one to first initialize the DB (e.g., run a no-op task to create the DB, then clear it) so it actually tests the "DB exists but queue is empty" case.
- Fix --json help text: say "skip confirmation" instead of "implies --force" - Fix test_list_json_empty_queue to actually test DB-exists-but-empty case Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Summary
--jsonflag totq list,tq logs, andtq clearcommands for structured JSON outputcommandcolumn to queue schema so consumers can see what's running (e.g.,./gradlew build)TestJsonSchemaContractstest class to enforce JSON structure stability for programmatic consumersMotivation
Enable agents and status lines to programmatically read task queue state. For example, a Claude Code status line can now show "Queue: 1 running (
./gradlew build), 2 waiting" by parsingtq list --json.JSON Schemas
tq list --json{ "tasks": [{"id": 1, "queue_name": "global", "status": "running", "command": "./gradlew build", ...}], "summary": {"total": 1, "running": 1, "waiting": 0} }tq logs --json{"entries": [{"event": "task_completed", "timestamp": "...", "task_id": 1, ...}]}tq clear --json{"cleared": 5, "success": true}Test plan
tq list --json | jq .produces valid JSONtq logs --json | jq .produces valid JSONtq clear --jsonskips confirmation and outputs JSON🤖 Generated with Claude Code