Metadata-Version: 2.4
Name: ktr-cli
Version: 0.1.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` 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:

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

From the repository root:

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

To run checks locally:

```bash
uv run pytest
gate
```

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

## First auth setup

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

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

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

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

## Output format

Default output is JSON. List-style commands support:

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

Use:

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

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