npm package: @kntic/kntic
Description: KNTIC CLI — bootstrap and manage KNTIC projects
Author: Thomas Robak
Latest version: 0.10.0

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

```bash
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** | `screen` binary not found in `$PATH` | `⚠ screen not found — optional, needed for \`kntic start --screen\`` |

## Commands

### `kntic usage`

List all available sub-commands.

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

```bash
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](#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.

```bash
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:
```bash
docker compose -f kntic.yml --env-file .kntic.env up --build
```

---

### `kntic stop`

Stop KNTIC services via Docker Compose.

```bash
kntic stop
```

Runs:
```bash
docker compose -f kntic.yml --env-file .kntic.env stop
```

---

### `kntic update`

Download the latest KNTIC bootstrap archive and update managed files.

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

```bash
npm test
```

Runs tests using the Node.js built-in test runner:
```bash
node --test src/**/*.test.js
```

## License

[MIT](LICENSE)