@kntic/kntic

KNTIC CLI — bootstrap and manage KNTIC AI-orchestrated projects.

Requirements

• Node.js >= 18.0.0
• Docker (with docker compose v2) — required for kntic start / kntic stop
• GNU screen (optional) — needed for kntic start --screen
• Git (optional) — enables auto-detection of GIT_HOST, GIT_REPO_PATH, and GITLAB_TOKEN during kntic init

Installation

npm install -g @kntic/kntic

Preflight Checks

When running kntic init, the CLI performs automatic preflight checks before downloading the bootstrap archive. All checks are warnings only — they never block execution.

| Check | Condition | Warning | |-------|-----------|---------| | Platform | process.platform !== "linux" | ⚠ Non-Linux detected (<platform>) — KNTIC is designed for Linux, other platforms may have issues | | Docker | docker binary not found in $PATH | ⚠ docker not found — required for \kntic start`| | **Screen** |screenbinary not found in$PATH|⚠ screen not found — optional, needed for `kntic start --screen`` |

Commands

kntic usage

List all available sub-commands.

kntic usage

kntic init

Download and extract the KNTIC bootstrap template into the current directory. Sets up the .kntic/ directory structure, kntic.yml, and .kntic.env.

kntic init [--quick | -q | --interactive | -i]

| Option | Description | |--------|-------------| | --interactive, -i | Default. Walks through all .kntic.env values interactively, prompting for each variable. Auto-detected values are pre-filled as defaults. Skips KNTIC_VERSION and already-detected GITLAB_TOKEN. | | --quick, -q | Non-interactive mode. Auto-detects GIT_HOST and GIT_REPO_PATH from the git origin remote (SSH and HTTPS). Extracts GITLAB_TOKEN from HTTPS credentials if available (glpat-* tokens). |

What it does:

1. Runs preflight checks
2. Fetches version metadata from the bootstrap artifact URL
3. Downloads and extracts the bootstrap archive (merges .gitignore if one already exists)
4. Appends KNTIC_VERSION=<version> to .kntic.env
5. Auto-detects git remote information and fills GIT_HOST, GIT_REPO_PATH, and GITLAB_TOKEN
6. (Interactive mode only) Prompts for remaining .kntic.env values

kntic start

Build and start KNTIC services via Docker Compose.

kntic start [--screen]

| Option | Description | |--------|-------------| | --screen | Wrap the Docker Compose process in a GNU screen session. The session name is read from KNTIC_PRJ_PREFIX in .kntic.env, falling back to the current directory name. Skipped if already inside a screen session or if screen is not available. |

Runs:

docker compose -f kntic.yml --env-file .kntic.env up --build

kntic stop

Stop KNTIC services via Docker Compose.

kntic stop

Runs:

docker compose -f kntic.yml --env-file .kntic.env stop

kntic update

Download the latest KNTIC bootstrap archive and update managed files.

kntic update [--lib-only] [--compose]

| Option | Description | |--------|-------------| | --lib-only | Update only .kntic/lib/ (skip ADRs, hooks, and weights). | | --compose | Also replace kntic.yml from the bootstrap template. Creates a backup at kntic.yml.bak before overwriting. |

Default update scope (without --lib-only):

| Path | Strategy | |------|----------| | .kntic/lib/ | Replaced — cleared and re-extracted | | .kntic/adrs/ | Replaced — cleared and re-extracted | | .kntic/hooks/gia/internal/ | Updated — existing files overwritten, new files added, unlisted files preserved | | .kntic/hooks/gia/specific/ | Bootstrap only — extracted only if the directory does not already exist (user customizations are never overwritten) | | .kntic/gia/weights.json | Replaced if present in the archive | | .kntic.env | Merged — new variables from the template are appended with their comments; existing values are never overwritten | | KNTIC_VERSION | Updated in .kntic.env to the latest version |

Environment Variables

The .kntic.env file contains project configuration:

| Variable | Description | |----------|-------------| | ANTHROPIC_API_KEY | API key for Anthropic (used by the orchestrator engine) | | UID | Host user ID for container user mapping | | GID | Host group ID for container user mapping | | GITLAB_TOKEN | GitLab personal access token (glpat-*) | | GIT_HOST | Git server hostname (auto-detected from origin remote) | | GIT_REPO_PATH | Repository path on the git server (auto-detected from origin remote) | | KNTIC_VERSION | Bootstrap version (set automatically by kntic init / kntic update) | | KNTIC_PRJ_PREFIX | Project prefix used for screen session naming in kntic start --screen |

Services

Defined in kntic.yml:

| Service | Container | Image | Port | |---------|-----------|-------|------| | Dashboard | control-dashboard | kntic/dashboard:latest | 8002 | | Orchestrator | control-engine | nexus.kommune7.wien/kntic/kntic-engine:latest | — |

Both services run as ${UID}:${GID} (non-root) and use .kntic.env for environment configuration.

Testing

npm test

Runs tests using the Node.js built-in test runner:

node --test src/**/*.test.js

License

MIT