Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.khal.ai/llms.txt

Use this file to discover all available pages before exploring further.

This is the verified first-run path for a Field Delivery Engineer using the public khal CLI.
Install the CLI from npmjs. npmjs is npm’s default registry, so no registry flag is normally needed. Do not configure GitHub Packages for this flow; if a GitHub Packages entry exists for app-kit, treat it as non-authoritative for FDE installs.

​
0. Prerequisites

Install current Node and Bun before you start: 
node --version    # Node.js 20+; Node.js 22 is used in app-kit CI
npm --version     # npm 10+ works
bun --version     # required by generated app/service/workflow repos
Private KHAL app repos live in KHAL Gitea. Use the repo URL and credentials from the internal Gitea UI or onboarding note when you install from a private source. GitHub authentication is only relevant for the public docs repo and the GitHub-hosted app-kit/desktop exceptions.

​
1. Install khal from npmjs

Use the package @khal-os/app-kit. The binary is khal. 
npm install --global @khal-os/app-kit@latest
khal --version
The currently verified npmjs latest during this docs update was: 
1.0.57
Then inspect the available templates: 
khal new --list
Expected shape: 
Bundled templates:
  app        v1.0.57
  service    v1.0.57
  workflow   v1.0.57

​
2. Log in to a target

On a workstation with a browser: 
khal auth login --target dev
On SSH/headless/agent sessions, print the URL instead of trying to open a browser: 
khal auth login --target dev --no-browser
The CLI prints a WorkOS/AuthKit URL and listens for the localhost callback. It stores only the returned KhalOS session token. Verify identity and recovery state without printing secrets: 
khal auth status --target dev --json
khal whoami --target dev --json
khal auth status --json exits 0 even when unauthenticated and prints the next login command. khal whoami --json exits 2 when no credential exists.

​
3. Scaffold a new app, service, or workflow

For an app repo: 
khal new app my-first-app
cd my-first-app
For backend-only or workflow-first work: 
khal new service my-first-service
khal new workflow my-first-workflow
Generated repos are git-native KHAL apps: repo + branch + khal-app.json. Do not publish generated app repos to npm.

​
4. Build and typecheck locally

Generated repos use Bun: 
bun install
bun run build
bun run typecheck
A clean scaffold should pass all three before you touch a shared target.

​
5. Dry-run install before mutation

From the generated repo root: 
khal install . --target dev --dry-run --json
A clean scaffold reports a passing summary and zero blocking checks: 
{
  "summary": {
    "status": "pass",
    "message": "Dry-run preflight passed; no mutations were performed."
  }
}
For a hosted app repo, always pass an explicit branch: 
khal install <private-khal-gitea-repo-url> --branch dev --target dev --scope shared --dry-run --json

​
6. Install after dry-run passes

After login, permission, and a clean dry-run: 
khal install . --target dev --scope shared
For a hosted repo: 
khal install <private-khal-gitea-repo-url> --branch dev --target dev --scope shared
If the target denies the mutation, ask for the permission named by the CLI. The current install path usually requires os.marketplace.install.

​
7. Useful proof commands

khal context --target dev --text
khal doctor --target dev
khal logs <app-id> --target dev --tail 50
khal status <app-id> --target dev --json
khal open <app-id> --target dev --check --json
status and open are currently hidden compatibility helpers. They are useful for proof, but they are not yet part of the public khal --help ladder.

​
Troubleshooting

​
khal --version is stale

which khal
npm view @khal-os/app-kit dist-tags --json
npm cache clean --force
npm install --global @khal-os/app-kit@latest

​
GitHub Packages shows a different version

Ignore it for FDE CLI installation. npmjs is canonical for @khal-os/app-kit.

​
Private Gitea repo fetch fails

Authenticate source control through the internal Gitea path from onboarding: 
tea login list
tea whoami
git ls-remote <private-khal-gitea-repo-url>
For SSH remotes, register your SSH key in Gitea first and use the SSH clone URL. Do not print or commit tokens, credential-helper output, or private remote URLs in public docs/issues.

​
What was dogfooded

This page was written after running the path from a clean directory with npmjs @latest: 
npm install @khal-os/app-kit@latest
./node_modules/.bin/khal --version
./node_modules/.bin/khal auth login --target dev --no-browser
./node_modules/.bin/khal new app fde-demo-app
./node_modules/.bin/khal new service fde-demo-service
./node_modules/.bin/khal new workflow fde-demo-workflow
# for each generated repo:
bun install
bun run build
bun run typecheck
khal install . --target dev --dry-run --json
All three generated template kinds installed dependencies, built, typechecked, and passed install dry-run with zero blocking checks.