Installation and Setup
Install the CLI
npm install -g @klarocards/cli
Requires Node.js 18 or higher. Once installed, the klaro command is available globally.
Log in to your account
klaro login
You'll be prompted for your email and password. Your session token is stored locally in ~/.klaro/secrets.json and kept separate from the rest of the configuration.
For non-interactive environments (CI pipelines, AI agents like Claude Code), use --env to read credentials from environment variables instead of prompting:
export KLARO_LOGIN="you@example.com"
export KLARO_PASSWORD="your-password"
klaro login --env
This is the recommended approach when an AI agent needs to authenticate on your behalf -- set the variables in your shell session and let the agent run klaro login --env without any interactive prompt.
To check who is currently logged in:
klaro whoami
Select a project
Most commands need a project context. A project is identified by its subdomain -- the first part of your Klaro Cards URL. For example, if your project lives at https://my-project.klaro.cards, the subdomain is my-project.
List the projects you have access to, then pick one:
klaro ls projects
klaro use my-project
From this point on, all commands target my-project by default. You can always override the project on a single command with -p:
klaro ls -p another-project
If your project is hosted on a dedicated instance (e.g. https://my-project.klaro.yourdomain.com), see Target a different Klaro instance to configure the API URL first.
Browsing Your Project
List cards
Cards live on boards. You can find a board's identifier in its URL (e.g. https://my-project.klaro.cards/boards/{workspace}/backlog means the board is backlog), or list them with klaro ls boards.
klaro ls -b backlog # list cards from the backlog board
klaro ls -b backlog -l 50 # show more results
klaro ls -b backlog --dims progress,assignee # add dimension columns
klaro ls -b backlog -f status=open # filter by dimension value
If you mostly work on the same board, set it as the default so you can omit -b in subsequent commands:
klaro config set board backlog
klaro ls # now uses backlog by default
All the commands in the rest of this guide assume a default board has been set.
Explore the project structure
List the boards and dimensions available in your project:
klaro ls boards
klaro ls dimensions
Get details about a specific board or dimension:
klaro describe board backlog # see the board's filters
klaro describe dimension status # see allowed values
Reading and Editing Cards
Read a card
klaro read 42
This renders the card as syntax-highlighted markdown in your terminal. To include dimension values (as YAML frontmatter):
klaro read 42 --dims progress,assignee
Use --raw to get plain markdown without terminal formatting, useful for piping:
klaro read 42 --raw
Edit a card interactively
klaro edit 42
This opens the card in your $EDITOR. When you save and close, the changes are pushed back to Klaro. You can edit several cards in sequence:
klaro edit 10 11 12
Include dimensions so you can update them in the editor too:
klaro edit 42 --dims progress,assignee
Update a card from a file or stdin
The write command updates a card's content without opening an editor, which is great for scripts and AI agents:
klaro write 42 -f card.md # from a file
cat card.md | klaro write 42 # from stdin
A common pattern is to read a card, transform it, and write it back:
klaro read 42 --raw | some-transform | klaro write 42
Creating and Updating Cards
Create a card
The simplest form takes a title:
klaro create "Fix the login page"
You can set dimensions at creation time:
klaro create "Fix the login page" progress=todo assignee=Alice
Create from a markdown file or from stdin:
klaro create @spec.md -b backlog
cat spec.md | klaro create -b backlog
Use --edit to open the card in your editor right after creation:
klaro create "Draft: new feature" --edit
Duplicate a card
Pipe read into create:
klaro read 3 --raw | klaro create
klaro read 3 --raw | klaro create assignee=Bob # duplicate and reassign
Update dimensions
klaro update 42 progress=done
klaro update 10 11 12 progress=done # batch update
Delete cards
klaro del 42
klaro del 10 11 12
Managing Attachments
Attach files to a card
klaro attach 42 photo.jpg
klaro attach 42 a.jpg b.pdf # multiple files at once
klaro attach 42 cover.jpg --cover # set as card cover image
klaro attach 42 doc.pdf -d "API specification" # with a description
List and remove attachments
klaro ls attachments 42 # list attachments on a card
klaro detach 42 <uuid> # remove attachment and its file
klaro detach 42 <uuid> --keep-file # remove the attachment record only
Working Offline
The fetch/sync workflow lets you download cards as local markdown files, edit them with any tool, and push changes back.
Download cards
klaro fetch 1 2 3
klaro fetch 1 --dims progress # include dimensions in the file
Cards are saved as markdown files in the current directory.
Edit locally, then sync
Edit the downloaded files with any editor or tool, then push changes back:
klaro sync # upload changes and delete local files
klaro sync --keep # upload changes but keep local files
klaro sync --dry-run # preview what would be synced
Configuration
Save defaults
If you always work with the same board or dimensions, save them as defaults so you don't have to type them every time:
klaro config set board backlog
klaro config set dims progress,assignee
Or save defaults on the fly with --save-defaults:
klaro ls --dims progress --board backlog --save-defaults
View your current configuration:
klaro config list
Remove a default:
klaro config unset board
Target a different Klaro instance
By default the CLI connects to https://api.klaro.cards. If your organization uses a dedicated Klaro instance on its own domain, configure the API URL to point to it:
klaro config set api_url https://api.klaro.yourdomain.com
Reset to the default:
klaro config unset api_url
Project-local configuration
Run klaro init . in a project directory to create a local .klaro/ folder. When present, the CLI uses it instead of the global ~/.klaro/ configuration. This is useful for repositories where the team shares a common project or board default via version control (commit config.json, gitignore secrets.json).
klaro init .
echo "secrets.json" >> .klaro/.gitignore
Quick Reference
Run the built-in cheatsheet for a compact overview of all commands:
klaro cheatsheet # markdown format (AI-friendly)
klaro cheatsheet --table # table format (human-friendly)
For detailed help on any command:
klaro --help
klaro <command> --help