CLI tool for the Knowledge Stack platform. Wraps the auto-generated ksapi Python SDK with a Click-based command interface using a resource-first routing pattern.
kscli folders list
kscli folders describe <id>
kscli documents create --name "My Doc" --parent-path-part-id <id>
kscli chunks search --query "semantic search" --folder-id <id>
Requires Python 3.12+ and uv.
# From PyPI
uv tool install kscli
# From source
git clone https://github.com/knowledgestack/ks-cli.git
cd ks-cli
uv sync --all-extras --group devCreate an API key under My Account / API Keys after signing up on app.knowledgestack.ai.
kscli login --api-key <your-api-key>You can also point at a different environment:
kscli login --api-key <your-api-key> --url https://api.knowledgestack.ai# Verify identity
kscli whoami
# Browse folders
kscli folders list
kscli folders list --format tree
# Work with documents
kscli documents list --folder-id <id>
kscli documents describe <doc-id>
kscli documents ingest --name "report.pdf" --file ./report.pdf --parent-path-part-id <id>
# Search chunks
kscli chunks search --query "quarterly revenue" --folder-id <id>| Command | Description |
|---|---|
login |
Authenticate with a user-scoped API key |
logout |
Remove stored credentials |
whoami |
Show current authenticated identity |
settings environment <name> |
Set environment preset (local/prod) |
settings show |
Print resolved configuration |
Each resource group supports a subset of verbs (list, describe, create, update, delete, and resource-specific actions):
| Resource | Verbs |
|---|---|
folders |
list, describe, create, update, delete |
documents |
list, describe, create, update, delete, ingest |
document-versions |
list, describe, create, update, delete, contents, clear-contents |
sections |
describe, create, update, delete |
chunks |
describe, create, update, update-content, delete, search |
tags |
list, describe, create, update, delete, attach, detach |
workflows |
list, describe, cancel, rerun |
tenants |
list, describe, update, delete, list-users |
users |
update |
permissions |
list, create, update, delete |
invites |
list, create, delete, accept |
threads |
list, describe, create, update, delete |
thread-messages |
list, describe, create |
chunk-lineages |
describe, create, delete |
path-parts |
list, describe |
Control output with --format / -f (can appear anywhere in the command):
kscli folders list --format json # JSON output
kscli folders list -f yaml # YAML output
kscli folders list -f table # Rich table (default)
kscli folders list -f tree # Tree view for hierarchical data
kscli folders list -f id-only # Just IDs, one per line (useful for piping)
kscli folders list --no-header # Suppress table headersThe default format can be set via KSCLI_FORMAT env var or kscli settings.
Configuration resolves in order: CLI flags > environment variables > config file > defaults.
| Environment Variable | Description | Default |
|---|---|---|
KSCLI_BASE_URL |
API base URL | http://localhost:8000 |
KSCLI_FORMAT |
Default output format | table |
KSCLI_VERIFY_SSL |
Enable SSL verification | true |
KSCLI_CA_BUNDLE |
Path to custom CA certificate bundle | (system default) |
KSCLI_CONFIG |
Config file path | ~/.config/kscli/config.json |
KSCLI_CREDENTIALS_PATH |
Credentials file path | /tmp/kscli/.credentials |
See docs/configuration.md for the full configuration reference.
# Install dev dependencies
make install-dev
# Lint
make lint
# Lint + autofix
make fix
# Type check
make typecheck
# Run unit tests
make test
# Run full pre-commit checks (lint + typecheck + tests)
make pre-commitE2E tests require a running ks-backend instance. See docs/e2e-testing.md for the full guide.
# Quick start (with ks-backend checked out alongside ks-cli):
cd ../ks-backend
make e2e-stack # Start Docker stack (postgres, API, worker)
make e2e-prep # Seed database
cd ../ks-cli
make e2e-test # Waits for API readiness, then runs testsThe GitHub Actions pipeline (.github/workflows/workflow.yml) runs three jobs:
- lint — ruff + basedpyright
- e2e — spins up the ks-backend Docker stack, seeds data, runs CLI e2e tests
- release — semantic-release to PyPI (gated on both lint and e2e passing)
See docs/ci.md for pipeline details.
- Authentication — Auth flow, credential caching, token refresh
- Configuration — Environment variables, config file, presets
- E2E Testing — Running and writing e2e tests
- CI/CD Pipeline — GitHub Actions workflow details
- Design Patterns — Architecture and code patterns