ktr-cli 0.2.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 provides two command names:

• kantree: canonical command
• ktr: short alias

Commands cover authentication, discovery (org, team, workspace, view), cards, search, import/export, webhooks, automations, and raw API requests.

Install

Requirements:

• Python 3.11+
• A Kantree API key (X-Api-Key)
• Your Kantree API base URL

Install from PyPI:

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

Auth Setup

Start with the local guide:

kantree auth guide

For an on-prem Kantree environment:

export KANTREE_API_KEY="..."
kantree auth set \
  --profile work \
  --base-url https://kantree.example.com/api/1.0 \
  --api-key-env KANTREE_API_KEY
kantree auth show
kantree auth test
kantree me

Profiles store connection metadata: the API base URL and the environment variable name that contains the API key. The key value is never written to config. API key environment variable names must match [A-Za-z_][A-Za-z0-9_]*. On first run, auth set selects the target profile; pass --no-use when you only want to create or edit a profile without making it active.

Use kantree auth, kantree auth show, kantree auth status, or kantree auth current to inspect active profile metadata without printing secrets.

Config path:

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

You can also pass connection settings per command:

kantree --base-url https://kantree.example.com/api/1.0 me

The API key still comes from KANTREE_API_KEY or the resolved profile environment variable.

Resolution precedence:

1. Profile: root --profile, KANTREE_PROFILE, active profile, default
2. Base URL: root --base-url, KANTREE_BASE_URL, profile, internal default
3. API key env name: KANTREE_API_KEY_ENV, profile api_key_env, KANTREE_API_KEY
4. API key value: direct KANTREE_API_KEY, then the resolved API key env var

When setup fails:

• Missing API key: run kantree auth show and export the env var shown in resolved.next_step.
• Authentication failed (401): check that the key is current and matches the base URL, then run kantree auth test.
• Forbidden (403): the key may be valid, but the user may lack permission for the workspace, org, resource, or action.
• TLS/private CA: set REQUESTS_CA_BUNDLE or install the CA in system trust.

Workspace Usage

Most commands need a workspace. Use one of:

kantree card list --workspace Ops
kantree card list --workspace-id 42
kantree --workspace Ops card list
KANTREE_WORKSPACE=Ops 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

Set defaults per profile:

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

Delete commands are stricter and require explicit selectors.

kantree workspace delete --workspace-id 42 --yes

Output

Default output is JSON. List-style commands support:

• table
• tsv
• ids
• ndjson

Use:

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

--verbose enables extra columns when supported.

Common Commands

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

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

Raw API Requests

Use api routes to see the configured base URL, derived spec URL, and safe starting examples:

kantree api routes
kantree api spec

api request is the escape hatch for endpoints without a first-class wrapper. Paths must be relative to the configured base URL; absolute URLs are rejected.

kantree api request GET /projects/42/cards --query page=1 --include-headers
kantree api request POST /cards/7/comments \
  --body '{"message":"hello"}' \
  --header X-Trace-Id:manual-check \
  --dry-run
kantree api request POST /importers/spreadsheet/discover \
  --form delimiter=, \
  --file spreadsheet=cards.csv \
  --dry-run
kantree api request GET /me --output me.json

Successful raw requests emit a JSON envelope with status and data. --include-headers adds selected response headers such as Content-Type, X-Kantree-NextPage, request ids, and retry hints. Sensitive header names are redacted or omitted. Raw failures also emit a JSON diagnostic envelope and exit nonzero, preserving the API body when it is JSON and summarizing non-JSON HTML or proxy text.

Failure Recovery

• Missing API key or base URL: run kantree auth guide, then kantree auth set and kantree auth test. On first run, auth set activates the profile.
• Wrong hosted/on-prem base URL: rerun with root --base-url or update the active profile.
• Private CA or certificate verification failure: install the CA chain or set REQUESTS_CA_BUNDLE=/path/to/private-ca-chain.pem.
• 401 or 403: verify the active profile, key, user permissions, and whether a proxy forwards X-Api-Key. Do not keep retrying mutating commands.
• 502, 503, or 504: read-only requests are retried automatically; mutation requests are not. Check reverse proxy and upstream Kantree health.
• 200 text/html or login HTML in a raw api request response: suspect a proxy login page, missing /api/1.0, wrong base URL, or SSO/WAF rewrite.
• Output write failure: choose an existing writable parent directory.

Safety And Help

• 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.
• Run kantree auth guide when credentials or the base URL are not configured.