Metadata-Version: 2.4
Name: ktr-cli
Version: 0.2.0
Summary: Unofficial command-line client for the Kantree API.
Author: Sebastien De Reviere
License-Expression: Apache-2.0
Requires-Dist: click>=8.3,<9
Requires-Dist: requests>=2.33,<3
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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:

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

## Auth Setup

Start with the local guide:

```bash
kantree auth guide
```

For an on-prem Kantree environment:

```bash
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:

```bash
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:

```bash
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:

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

Delete commands are stricter and require explicit selectors.

```bash
kantree workspace delete --workspace-id 42 --yes
```

## Output

Default output is JSON. List-style commands support:

* `table`
* `tsv`
* `ids`
* `ndjson`

Use:

```bash
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

```bash
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:

```bash
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.

```bash
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.
