ktr-cli 0.1.0__tar.gz

ktr_cli-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+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`

ktr_cli-0.1.0/README.md

@@ -0,0 +1,162 @@
+# 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`

ktr_cli-0.1.0/kantree_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Unofficial Kantree CLI package."""
+
+__version__ = "0.1.0"