ktr-cli 0.1.0

Unofficial command-line client for the Kantree API.

ktr-cli

Unofficial command-line client for the Kantree API.

This project is not affiliated with, endorsed by, or maintained by Kantree.

ktr-cli exposes:

• kantree: canonical command
• ktr: short alias

Commands are organized around Kantree workflows: auth, discovery (org, team, workspace, view), cards, search, import/export, webhooks, automations, and raw endpoint testing.

Install and run

• Python 3.11+
• uv
• A Kantree API key (X-Api-Key)

From PyPI:

uv tool install ktr-cli
kantree --help
ktr --help

From the repository root:

uv venv
uv sync --group dev
uv run kantree --help
uv run ktr --help

To run checks locally:

uv run pytest
gate

Real API smoke tests are opt-in only. See docs/guides/real-api-smoke-testing.md.

First auth setup

export KANTREE_API_KEY="..."
uv run kantree auth init
uv run kantree auth set \
  --profile work \
  --base-url https://kantree.io/api/1.0 \
  --api-key-env KANTREE_API_KEY
uv run kantree auth use work
uv run kantree auth test
uv run kantree me

auth set stores profile metadata only; the key value is never printed. Use uv run kantree auth or uv run kantree auth show to inspect active profile state and defaults.

Config path:

• $XDG_CONFIG_HOME/kantree/config.toml if XDG_CONFIG_HOME is set
• ~/.config/kantree/config.toml otherwise

Workspace-aware usage

Most commands need a workspace. Use one of:

uv run kantree card list --workspace Ops
uv run kantree card list --workspace-id 42
uv run kantree --workspace Ops card list
KANTREE_WORKSPACE=Ops uv run kantree card list

Resolution order:

1. Command-local --workspace-id / --workspace
2. Root kantree --workspace-id / --workspace
3. KANTREE_WORKSPACE_ID / KANTREE_WORKSPACE
4. Active profile default_workspace

If a command depends on a workspace, command-local wins.

Set defaults per profile:

uv run kantree workspace use Ops
uv run kantree workspace current
uv run kantree workspace current --resolve-remote

Delete commands are stricter and require explicit selectors.

uv run kantree workspace delete --workspace-id 42 --yes

Output format

Default output is JSON. List-style commands support:

• table
• tsv
• ids
• ndjson

Use:

uv run kantree --format table workspace list
uv run kantree --format tsv --fields id,title,state card list --workspace Ops
uv run kantree --format ids card list --workspace Ops

--verbose enables extra columns when supported.

Common command groups

uv run kantree org list
uv run kantree workspace list --org DSI
uv run kantree team list --org DSI
uv run kantree card list --workspace Ops --filter '@me'
uv run kantree card create --workspace Ops --title "Fix LDAP sync"
uv run kantree card edit 123 --state completed
uv run kantree search cards --query '@me'
uv run kantree search preset list
uv run kantree view list
uv run kantree webhook list --workspace Ops
uv run kantree automation list --workspace Ops
uv run kantree import ./cards.csv
uv run kantree kql validate '@me and state!=completed'
uv run kantree api request GET /me

Use uv run kantree --help and command-level --help for current flags and subcommand details.

Safety notes

• Keep API keys in env vars or a secret manager.
• auth show redacts key metadata only; avoid command-line secrets (--body) in shared terminals and history.
• Destructive commands and some destructive batches require explicit --yes.
• workspace delete ignores default workspace fallbacks and requires explicit selector.
• Prefer card archive when you need a reversible action.
• Use --dry-run where available before mutating commands.

Where to continue

• docs/README.md
• docs/style.md
• docs/guides/real-api-smoke-testing.md