The CLI for AI coding agents

How it works

uqplanner is a command-line tool that connects a code repository to a UQ Planner project. People use it to read and update tasks without leaving the terminal. AI coding agents — such as Claude Code — use it to take one task at a time, do the work in the repository, and report back with a comment and evidence (test videos, screenshots, logs) attached to the task. Everything happens as you: the CLI uses your API key, so it sees exactly your projects and permissions.

1. The CLI downloads your next open task as a Markdown file — description, epic, linked docs and comments included.
2. Your AI agent reads it, implements the change, tests it and writes a short report.
3. The CLI uploads the report and the evidence to the task and moves it to Awaiting Review.
4. A person reviews it on the board like any other work — and the loop moves on to the next task.

1. Get your API key

Sign in and open Account → API key. Your key (it starts with uqp_) is created the first time you visit. You can show and copy it again later.

• One key per person. It has no scopes and no expiry — it acts as you, with your permissions.
• Regenerate replaces it; the old key stops working immediately. Do this if a key leaks.
• Copy prompt for AI copies a ready-made briefing for an AI tool with your key, organisations and project keys filled in.
• Never commit the key or paste it into shared files.

2. Install the CLI

You need Node.js 18 or newer.

curl -fsSL https://planner.uniqtech.dev/api/cli/install | bash

irm https://planner.uniqtech.dev/api/cli/install.ps1 | iex

On macOS and Linux it installs into ~/.local/share/uqplanner with the uqplanner command in ~/.local/bin (make sure that folder is on your PATH); on Windows into %LOCALAPPDATA%\uqplanner. Update later with uqplanner upgrade; check the version with uqplanner --version.

3. Sign in and link a repository

uqplanner login uqp_xxxxxxxxxxxxxxxx   # verifies and saves the key
uqplanner whoami                          # you, your organisation, the linked project
uqplanner org                             # list organisations; switch: uqplanner org use "<name>"
uqplanner projects                        # list projects (key, id, name)
cd ~/code/website
uqplanner link <projectId>                # pin this repository to the project

link writes a small .uqplanner.json in the repository so later commands know the project (it is found from any sub-folder). The CLI keeps its working files in .uqplanner/ — add that folder to your .gitignore. Your key is stored in your home folder (~/.uqplanner/), never in the repository.

Work on tasks from the terminal

uqplanner next                 # your open tasks, best first → .uqplanner/queue.md
uqplanner tasks --mine         # a table of tasks (filters: --status, --type, --project)
uqplanner task pull WEB-42     # → .uqplanner/tasks/WEB-42.md
# edit the file: status, assignees, labels, dates, description, tick subtasks,
# add a new "### …" section at the end to post a comment
uqplanner task push WEB-42     # only what you changed is applied
uqplanner task new draft.md    # create a task from a Markdown file
uqplanner upload WEB-42 ./screenshot.png

The task file

---
key: WEB-42
project: WEB
type: TASK                  # EPIC | TASK | BUG | SUBTASK
status: In Progress         # one of the project's workflow statuses
parent: WEB-40
blockedBy: [WEB-39]
assignees: [dev@example.com]
labels: [frontend]
start: 2026-11-03
due: 2026-11-07
fields: { Priority: High }  # card-template custom fields
updatedAt: 2026-11-04T09:12:00.000Z   # keep as received
---
# Close the dialog on Escape

Description in Markdown.

<!-- planner:subtasks -->
## Subtasks
- [ ] WEB-43 Handle Escape key        # tick to move it to Done
- [ ] Add a test                       # a line without a key creates a subtask

<!-- planner:comments -->
## Comments
### Done
A new section at the end is posted as a comment.

If someone changed the same field in the web app since you pulled, push stops with a conflict and saves the latest version to the same file — redo your edit there and push again.

Let an AI agent run tasks

The CLI drives Claude Code (--agent claude, the default) or Yuki (--agent yuki). Assign tasks to yourself in Planner first — the agent works your queue.

1. Install the /uqplanner-run skill into your AI tool (one-time):

   uqplanner install-skill            # or: --agent yuki, --all (also every linked repo)

2. Run the loop from the linked repository:

   uqplanner run

   It prepares one task, starts the agent with the /uqplanner-run skill, then syncs the results — and repeats until your queue is empty. If it is interrupted, uqplanner run (or uqplanner resume) carries on where it stopped; --hard starts from a clean slate.
3. Prefer to drive it yourself? Run the three steps separately: uqplanner prepare, then type /uqplanner-run in Claude Code, then uqplanner sync.
4. With several repositories linked, uqplanner runAll runs the loop on each (--mode sequence or parallel).

What the agent is told to do

• Read the task's comments first — the newest comment overrides the description.
• Update the default branch before changing anything.
• Plan, implement and test the change.
• Capture evidence, preferring a Cypress or screen-recording video, then a screenshot, then test output.
• Write a comment: what changed, how it was tested, anything left over.
• Commit locally with a one-line message named after the task.
• Mark the task done — unless it got blocked, in which case it says why in the comment and leaves the task open.

Evidence and comments

On sync, the CLI posts the agent's comment on the task, uploads every evidence file as an attachment (up to 50 MB each), and moves finished tasks to Awaiting Review. Reviewers see the video or screenshots right in the task window — the agent's work arrives with its receipts. You can attach evidence by hand at any time with uqplanner upload WEB-42 ./video.mp4.

Which task the agent picks

From the open tasks assigned to you, oldest first within each group:

1. In Progress — finish what is started;
2. statuses starting with AI: (e.g. AI: Ready) — work you queued for the agent on purpose;
3. Ready, Todo or To Do;
4. Changes Requested;
5. anything else, with Blocked last.

Tasks whose status ends in “done”, or is Awaiting Review or Closed, are skipped.

Using the HTTP API directly

Everything the CLI does is plain HTTP with your key in an Authorization: Bearer header (add X-Organization-Id if you belong to several organisations).

curl -H "Authorization: Bearer $UQP_API_KEY" https://planner.uniqtech.dev/api/user-tasks/WEB-42/markdown
curl -X PUT -H "Authorization: Bearer $UQP_API_KEY" -H "Content-Type: text/markdown" \
     --data-binary @WEB-42.md https://planner.uniqtech.dev/api/user-tasks/WEB-42/markdown

The full endpoint list, written for AI tools, is public at https://planner.uniqtech.dev/llms.txt.

Command reference

Troubleshooting

• “command not found: uqplanner” — add ~/.local/bin to your PATH and open a new terminal.
• 401 / invalid key — the key was regenerated. Copy the current one from Account → API key and run uqplanner login again.
• No tasks picked — the loop only takes open tasks assigned to you in the linked project.
• Wrong organisation — uqplanner org use "<name>".
• 409 on push — someone edited the task meanwhile; the file now holds the latest version — redo your change.
• 400 on push — the message says what is wrong: an unknown status (must be one of the workflow's), an unknown person, a bad date or a wrong parent type.