liveplanner is a command line for the liveplanner API. It is built first for coding agents (an agent working in your repository, or one updating your board while you talk to it) and second for scripts: finding plans, reading a tab as text, adding and moving cards, filling in Sheets, answering comments, and syncing plans to files.
It sits beside the MCP server, not in place of it. Both call the same API with an API token, and the API owns every change, so an older copy of the CLI never writes the old way.
Install
The CLI is the npm package @liveplanner/cli and needs Node 22 or later. Run it without installing:
npx @liveplanner/cli --help
or install it, which gives you the liveplanner command:
npm install -g @liveplanner/cli
liveplanner --version
The examples below use the installed liveplanner; with npx, put npx @liveplanner/cli in its place.
Sign In
You need a liveplanner account: the CLI acts as you, through an API token, and never as a guest. There are three ways to give it one. Whichever you use, the CLI checks the token with the API before keeping it.
In the Browser
liveplanner auth login
The CLI opens a sign-in page in your browser (and prints its address, in case the browser does not open). Sign in if you are not already, and you reach an approval card, Connect liveplanner CLI. Leave Read-only access off to let the CLI change plans, or switch it on so it can find and view plans but not create, edit, delete or share them. The card also says where the access goes: your own computer, 127.0.0.1 and a port number. Choose Connect, and the page says You're signed in: return to your terminal.
The terminal waits up to ten minutes for you. If the browser cannot reach it (on a remote machine, say), use a device code instead.
On a Machine Without a Browser
liveplanner auth login --device
The terminal prints a page address, https://liveplanner.app/oauth/device, and a code of eight letters such as BCDF-GHJK, plus a link with the code already filled in. Open the page on any device, sign in, type the code under Code shown in your terminal and choose Continue. You then see a Connect liveplanner CLI card with the same Read-only access switch; choose Connect, and the page says You're connected. The terminal carries on by itself.
A code lasts ten minutes. If the page says it couldn't find the code, check it and try again; if it has expired, run the command again for a new one. Choosing Cancel on the page stops the terminal waiting. Only enter a code that a terminal you are using is showing you.
With an API Token
For CI, sandboxes and agents, create a token in Settings, under Account, then API Tokens, and either set it for the commands you run:
export LIVEPLANNER_TOKEN=lwt_your_token_here
or store it for this machine, reading it from stdin:
printf %s "$TOKEN" | liveplanner auth login --with-token
LIVEPLANNER_TOKEN takes precedence over a stored sign-in. There is deliberately no --token flag, because a token on the command line ends up in shell history and transcripts.
Check or Sign Out
liveplanner auth status # host, account, token name, role, expiry, and where it came from
liveplanner auth logout # revoke the stored token and forget it
auth status never prints the token itself, and warns you when it has under 14 days left. auth logout revokes the token with liveplanner, so it stops working everywhere at once. It will not revoke a token from LIVEPLANNER_TOKEN, which is not the CLI's to revoke: unset the variable, or revoke that token in API Tokens.
The browser and device sign-ins create an ordinary API token named liveplanner CLI. It appears in API Tokens beside any others (with a Read-only badge if you chose that), lasts six months, and counts towards your ten. Signing in again on the same machine replaces it and revokes the old one.
Where Your Token Is Kept
A stored token goes in your operating system's own secret store: the macOS Keychain, the Secret Service on Linux (through secret-tool), or on Windows the token sealed to your user account by Windows' own data protection. Where that store is unavailable, the token is kept in ~/.config/liveplanner/credentials.json, readable only by you, and the CLI tells you so when it stores it there. If it finds that file readable by others, it tightens it and warns you.
Find and Read Plans
Commands are a resource, then a verb.
liveplanner project ls sprint # projects whose name contains "sprint"
liveplanner project view "Sprint 14" # one line per tab
liveplanner tab view "Sprint 14" # the first tab, as an outline
liveplanner tab view "Sprint 14" --tab Flow --view show --ref 0a78
liveplanner tab render "Sprint 14" --png sprint.png
project ls covers your personal library and every team you have joined, newest first. Wherever a command takes a plan, you can give its name, the start of its id, or a pasted liveplanner link; a share link acts through that link. A name that matches more than one plan is refused with the candidates, rather than guessed. --tab takes a tab name or the start of its id, and the first tab is used when you leave it out.
tab view reads a tab as text, the outline by default; --view picks comments, show (one element, with --ref) or find (with --text), and --budget fits it to about that many tokens. tab render writes a PNG or SVG preview and prints its path and size, never image bytes.
A few commands read liveplanner's catalogues rather than your plans, which helps before writing anything:
liveplanner template ls # the templates a project or tab can start from
liveplanner template view kanban # one template, as the outline of the tab it builds
Build and Change Plans
liveplanner project create "Sprint 14" --template kanban
liveplanner project create "Budget 2027" --template budget-planner
liveplanner tab add "Sprint 14" Roadmap --template project-planner # a new tab, empty or from a template
liveplanner tab rename "Sprint 14" Roadmap "Roadmap 2027"
liveplanner tab rm "Sprint 14" Scratch # delete one tab; the others stay
liveplanner edit "Sprint 14" --tab Flow -f ops.txt # edit operations on a tab
liveplanner changeset revert "Sprint 14" cs_tbrfqcvm1w
A change to a tab is one changeset, applied all or nothing and checked against the version of the tab you last read, so the CLI never silently overwrites someone else's work. Each write prints what changed, the new revision and the command that reverts it. Add --dry-run to see the plan without writing anything, and --summary to say what the change is for. liveplanner guide edit explains how edit operations read; for cards, boards, sheets and forms, the commands below are simpler.
project rm moves a plan to the Trash for 30 days, and project restore brings it back to its folder (or the top level, when that folder is gone); the CLI has no permanent delete.
Cards, Boards and Sheets
liveplanner item ls "Sprint 14" # the cards, by number such as #12
liveplanner item add "Sprint 14" "Fix login" --type task --status "To Do" --fields priority=high
liveplanner item move "Sprint 14" "#12" "In Progress"
liveplanner item set "Sprint 14" "#12" --fields assignee=Sam --clear due
liveplanner board add "Sprint 14" --preset sprint
liveplanner board set "Sprint 14" Kanban --columns "To Do,Doing,Review,Done"
liveplanner type ls "Sprint 14" # card types and their fields
liveplanner type apply "Sprint 14" -f types.json # add, change or delete card types
liveplanner sheet add "Budget 2027" --title Costs --csv costs.csv
liveplanner sheet get "Budget 2027" Costs A1:D20 # a sheet's cells by A1, formulas worked out
liveplanner sheet set "Budget 2027" Costs B2 1200 =B2*12
Cards, boards and sheets are named the way the editor shows them: a column by its name, a card by its number, a sheet by its title. These writes are not changesets: each lands at once, for everyone with the plan open.
Comments and Waiting
liveplanner comment ls "Sprint 14"
liveplanner comment add "Sprint 14" 0933 "Can we drop the Review column?"
liveplanner wait "Sprint 14" --for comment --timeout 600
liveplanner watch "Sprint 14" # stream changes until you stop it
wait blocks until someone comments or the plan changes (a burst of edits counts as one change), prints it and exits, which lets an agent respond to the people working beside it. Comments the CLI adds are yours.
Forms
A form on a Form tab has its own commands, so an agent can build one, publish it and check where its answers land:
liveplanner form add --starter rsvp --name "Summer Party" # a new project with a Form tab
liveplanner form get "Summer Party" # its questions, where responses go, its link
liveplanner form change "Summer Party" changes.json # up to 50 changes, all or nothing
liveplanner form share "Summer Party" publish # or close, or delete-link
liveplanner form try "Summer Party" answers.json # one test response, as the builder's Preview sends
A test response makes a card (or sheet row) titled Preview:, so you can see each answer land where you expect, then delete it.
Files, Exports and Pictures
liveplanner pull "Sprint 14" --to backup --svg # backup/sprint-14.liveplanner.json, plus an SVG per tab
liveplanner push backup/sprint-14.liveplanner.json # send back each tab whose elements changed
liveplanner export --all --to backup --format json,svg,md
To work in a plan beside your agent inside a developer tool, see liveplanner in Your Developer Tools.
pull writes the plan in the format the editor imports, and never overwrites a file holding changes you have not pushed yet (add --force to drop them). push sends each changed tab as a changeset; a tab that changed on liveplanner since you pulled it is refused and named, so pull again. Only elements travel: each changed tab's elements are replaced by the file's, so an element you removed from the file is removed from the tab, and a tab the plan lacks is created. Changes to a tab's name, theme or background are not sent (a tab a push creates goes up with its name), and no tab or plan is ever deleted by a push. Cards travel with the plan's item store, not with a tab, so a push never changes them. export --all writes every plan you can read, for backups and docs.
Help, Guides and the Agent Skill
liveplanner --help # the resources and four starting commands
liveplanner tab --help # a resource's verbs
liveplanner tab view --help # usage, flags and examples
liveplanner guide # how-tos: build, edit, views, comments, collaborate, workbench
liveplanner skill install --to ~/.claude/skills
liveplanner skill print > SKILL.md
Help is kept short so an agent pays only for what it asks. skill install writes a SKILL.md that tells a coding agent when to reach for the CLI; without --to it lists the usual skills folders (such as ~/.claude/skills for Claude Code). skill print writes the same file to stdout, for agents that keep their skills somewhere else. liveplanner api GET /projects calls any API path with your sign-in, as an escape hatch.
Output and Exit Codes
The CLI never prompts when its input or output is not a terminal, so it is safe in pipes, scripts and CI. stdout carries only data; hints, warnings and errors go to stderr. Output is compact text; --json gives the same data as JSON, --json=id,name picks fields, and -q prints only refs or ids. A list that was cut short ends with a line saying how to see the rest.
| Exit code | Meaning |
|---|---|
0 | Done |
1 | Refused: the input was understood but not accepted |
2 | Usage: the command line does not parse |
3 | Not found, or ambiguous: a plan, tab or element |
4 | Not signed in, or not allowed (a read-only token's writes) |
5 | Conflict: the tab changed since you read it; read, retry |
6 | Rate limited |
7 | Network or server failure |
Every error names what was wrong and suggests one command that fixes it. Set LIVEPLANNER_DEBUG=1 to see what the CLI is doing, on stderr.
Hosts and Profiles
The CLI talks to https://liveplanner.app unless you point it at another liveplanner host. For one command, add --host https://planner.example.com; for a shell, set LIVEPLANNER_HOST. To keep several, name them as profiles in ~/.config/liveplanner/config.toml and choose one with --profile or LIVEPLANNER_PROFILE:
default_profile = "work"
[profiles.work]
host = "https://planner.example.com"
Each profile keeps its own sign-in, and a profile for another host never contacts liveplanner.app. LIVEPLANNER_TOKEN goes to whichever host is active, so set LIVEPLANNER_HOST beside it. A host without accounts has no tokens, so the CLI cannot act there and says so; one without the sign-in server offers no browser or device sign-in, so use --with-token. If an instance needs a newer CLI for writes, the CLI refuses them and names the version to install.
Errors and Rate Limits
The CLI is subject to the same limits as any API client, per token: on the hosted service, 300 writes and 120 reads a minute. Over that, a command exits with 6 and asks you to wait a minute and retry. A read-only token's writes exit with 4. Errors and Rate Limits has the full list and the status codes behind these exit codes.
Usage Counts
The CLI counts which commands succeed, and which fail because of the server or the network, by the command's name only (never its arguments, your plans or the host), and sends the count to the host it talks to, as anonymous telemetry. The first time it counts one, it says so. Turn it off with liveplanner telemetry off, LIVEPLANNER_TELEMETRY=0 or DO_NOT_TRACK=1.
Keep It Safe
A full-access token can change and share everything you can. Give an agent a Read-only access
token when it only needs to read, keep LIVEPLANNER_TOKEN out of source control and logs, and
revoke a token from API Tokens (or with liveplanner auth logout) the moment you no longer
need it or think it may have leaked.
Was this article helpful?