A task manager CLI built for agents that run a shell
pt prints JSON by default, so an agent parses it directly and a script pipes it into jq. It needs no config file and no MCP support, only a shell and an API key. That makes it the way in for sandboxes, CI jobs and any agent that can run a command.
What is the PerspecTask CLI?
@perspectask/cli installs two identical commands, pt and the longer perspectask for systems where pt is taken. It covers the whole API: list your open tasks flat or as a tree, read one task with its subtree, create tasks and subtasks, and update status, priority, deadline and parents. Output is lean JSON with 3-character ids, and the package ships a SKILL.md that documents every command and flag for agents that load skills.
npm install -g @perspectask/cli
pt auth set --key "pt_live_..." # or export PERSPECTASK_API_KEY
pt tasks # open tasks, flat JSON
pt tasks a3f --tree # one goal with its subtree
pt tasks create "Renew passport" --deadline next-month --parent-id a3f
pt tasks update 7c2 --status IN_PROGRESSAdd --pretty when a human reads the output. Done tasks stay hidden unless you pass --show-completed, so an agent spends no context on finished work.
How agents use pt
Install and set the key
npm install -g @perspectask/cli, then pt auth set on your machine or PERSPECTASK_API_KEY in a sandbox that resets each run. It works in the same session, no restart.
Point the agent at SKILL.md
It sits next to the binary at $(npm root -g)/@perspectask/cli/SKILL.md: every command, flag, deadline token and status, written for a model to read once.
Hand back for review
A good loop: the agent marks a task IN_PROGRESS before it starts and WAITING when it is done, then you close it from the app. The workflow is yours to define; the CLI just moves tasks between statuses.
Frequently asked questions
- What is the best task manager CLI for AI agents?
- One that prints machine-readable output by default, keeps ids short and omits empty fields, because an agent pays for every token it reads. pt does all three: JSON by default, 3-character task ids, and only the fields that are set. It also ships a SKILL.md so an agent can learn the commands without reading docs.
- Do I have to install the CLI in every session?
- Only where the environment resets, like a cloud sandbox or a CI runner: there it is one npm install per run, with PERSPECTASK_API_KEY set as a secret. On your own machine it is installed once. If reinstalling bothers you, the MCP server is configured once in your client and loads in every session.
- How do I write deadlines in the CLI?
- Pass one shorthand token to --deadline: today, tomorrow, this-week, next-month, q3, w15, m11, y2027, or lifetime for no deadline. Use the dashed form in a shell, since an unquoted space splits the token in two. The same token works on create and update, and the canonical form the CLI prints back is also valid input.
- Can pt read my end-to-end encrypted tasks?
- No. Encrypted tasks are only decrypted in the PerspecTask app with your password, so the API and the CLI cannot read or modify them. They are hidden from pt tasks by default, and --include-encrypted shows them as placeholders without a title so you can see the tree shape.
- Is the PerspecTask CLI free?
- Yes. The CLI is free and Apache-2.0 licensed, and PerspecTask is free to start with API keys included, so you can try the whole setup at no cost.
Put your goals one command away
Create a free scoped key, run npm install -g @perspectask/cli, and let any agent with a shell plan and update your tasks.