### Install Kata with Go

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/install.md

Install the Kata binary using the Go toolchain. Ensure Go 1.26 or later is installed. The binary is placed in GOBIN or GOPATH/bin.

```go
go install go.kenn.io/kata/cmd/kata@latest
```

--------------------------------

### Install Zensical for Documentation

Source: https://github.com/kenn-io/kata/blob/main/docs/development/contributing.md

Install the Zensical documentation toolchain. This is a prerequisite for building and checking the project's documentation.

```sh
make docs-install
```

--------------------------------

### Initialize a Federated Project

Source: https://github.com/kenn-io/kata/blob/main/docs/design/federation.md

Use this command to create a new project that will serve as the hub in a federated setup. This command is part of the initial project setup.

```bash
kata init --project fedlab
```

--------------------------------

### Verify Kata Installation

Source: https://github.com/kenn-io/kata/blob/main/README.md

After installation, run this command to confirm that Kata has been installed correctly and to check its version.

```sh
kata version
```

--------------------------------

### Install Kata from Source with Custom GOBIN on macOS/Linux

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/install.md

Build and install Kata from source, specifying a custom GOBIN directory. Defaults to ~/.local/bin if GOBIN is not set.

```sh
make install GOBIN=/usr/local/bin
```

--------------------------------

### Check Kata Installation

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/install.md

Verify the installation by checking the Kata version and its help information.

```sh
kata version
kata --help
```

--------------------------------

### Build Kata from Source on macOS/Linux

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/install.md

Clone the Kata repository and use 'make install' to build and install the tool. This method is useful for development builds.

```sh
git clone https://github.com/kenn-io/kata.git
cd kata
make install
```

--------------------------------

### Start Kata Daemon in Read-Only Mode

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/remote-daemon.md

Use this command to start the daemon for unauthenticated read-only experiments. This mode permits GET requests only and relies on external network configurations for access control. It cannot be combined with `require_token_identity = true`.

```sh
kata daemon start --foreground --listen 100.64.0.5:7777 --insecure-readonly
```

--------------------------------

### Install Kata Update

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/install.md

Execute this command to download and install an available update for Kata from GitHub release assets. The update is verified before installation.

```sh
kata update
```

--------------------------------

### Generate Documentation Screenshots

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/federation.md

Run this command to generate preview assets for documentation screenshots. Ensure you have the necessary build tools installed.

```shell
make docs-screenshots
```

--------------------------------

### Install Kata on macOS or Linux

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/install.md

Use this command to download and install the latest Kata release using a shell script. The script detects your OS and architecture and verifies the download.

```sh
curl -fsSL https://katatracker.com/install.sh | bash
```

--------------------------------

### Start Kata Daemon

Source: https://github.com/kenn-io/kata/blob/main/docs/reference/cli.md

Starts the Kata daemon in the background. Use `--foreground` to keep it attached to the terminal, suitable for service managers or hosted deployments.

```sh
kata daemon start [--foreground] [--listen <host:port>] [--insecure-readonly]
```

--------------------------------

### Start Remote Daemon with CLI Flags

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/remote-daemon.md

Start the daemon in the foreground, specifying authentication token and enabling private network trust. This method is useful for temporary or direct command-line control.

```sh
KATA_AUTH_TOKEN=change-me KATA_TRUST_PRIVATE_NETWORK=1 \
  kata daemon start --foreground --listen 100.64.0.5:7777
```

--------------------------------

### Install Kata on Windows

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/install.md

Use this PowerShell command to download and install the latest Kata release. It bypasses execution policy for the download and execution.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://katatracker.com/install.ps1 | iex"
```

--------------------------------

### Configure GitHub App Installation Credential

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/github-sync.md

Use this TOML configuration for shared or hosted daemons to authenticate using a GitHub App installation. Ensure the App has read access to Metadata and Issues.

```toml
[[github_sync.app]]
host = "github.com"
owner = "example-org"
app_id = 12345
installation_id = 67890
private_key_path = "/var/lib/kata/github-app.pem"
```

--------------------------------

### Start Kata Session

Source: https://github.com/kenn-io/kata/blob/main/docs/workflows/agents.md

Initiate a Kata session from the workspace or specify a workspace path. Set the actor identity once using an environment variable.

```sh
kata quickstart
kata list --agent
```

```sh
export KATA_AUTHOR=codex-wesm-laptop
kata whoami --agent
```

--------------------------------

### Join Federated Project with Adoption

Source: https://github.com/kenn-io/kata/blob/main/docs/design/federation.md

Use this command to adopt an existing non-federated spoke project into a federated setup. This requires the enrollment to be created with `--adopt-existing` and preserves local issue state, excluding event history.

```bash
kata federation join --project fedlab \
  --hub-url http://<private-hub-ip>:7787 \
  --hub-project-id 1 \
  --token ... \
  --actor wesm \
  --push \
  --adopt-existing
```

--------------------------------

### Example Import Success Report

Source: https://github.com/kenn-io/kata/blob/main/docs/guide/migrating-from-beads.md

A successful import operation reports the number of issues, comments, and links that were processed.

```text
imported beads: created 128, updated 0, unchanged 0, comments 342, links 57
```

--------------------------------

### Setup Disposable Validation Run for GitHub Sync

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/github-sync.md

Prepare a temporary environment for validating GitHub sync functionality. This involves creating temporary directories for KATA_HOME and workspace, exporting necessary environment variables, and configuring the GitHub sync settings.

```sh
validation_home="$(mktemp -d)"
validation_ws="$(mktemp -d)"

export KATA_HOME="$validation_home"
export KATA_AUTHOR=github-sync-validation
export KATA_GITHUB_TOKEN="$EXAMPLE_GITHUB_TOKEN"

cat >"$KATA_HOME/config.toml" <<'EOF'
[github_sync]
token_env = "KATA_GITHUB_TOKEN"
token_host = "github.com"
EOF

cd "$validation_ws"
kata init --project github-sync-validation
kata sync github enable --repo example-org/example-repo --interval 24h
kata sync github once
kata sync github status --json
kata sync github once
kata list --status all --limit 20
kata show <imported-ref> --json
```

--------------------------------

### Link Repository to Vercel Project (CLI)

Source: https://github.com/kenn-io/kata/blob/main/docs/development/deploying-docs.md

Command to link the local repository root to an existing Vercel project. This is a one-time setup step.

```sh
vercel link
```

--------------------------------

### Vercel Project Configuration (JSON)

Source: https://github.com/kenn-io/kata/blob/main/docs/development/deploying-docs.md

Defines Vercel build settings including install, build commands, and output directory. This file ensures reproducible builds.

```json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": null,
  "installCommand": "uv sync --frozen --no-dev",
  "buildCommand": "uv run --frozen bash ./vercel-build.sh",
  "outputDirectory": "site"
}
```

--------------------------------

### Enable Tokenless Private Network Writes (CLI)

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/remote-daemon.md

Configure the Kata daemon to allow unauthenticated writes on a private network using command-line arguments. This method sets an environment variable and starts the daemon.

```sh
KATA_ALLOW_UNAUTHENTICATED_PRIVATE_NETWORK_WRITES=1 \
  kata daemon start --listen 100.64.0.5:7777
```

--------------------------------

### Kata Health and Information Commands

Source: https://github.com/kenn-io/kata/blob/main/docs/reference/cli.md

Commands to check the health of the Kata system, get the current user context, and access quickstart or version information.

```sh
kata health
```

```sh
kata whoami
```

```sh
kata quickstart
```

```sh
kata version
```

--------------------------------

### Build or Serve Documentation Site

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/install.md

Commands to build the documentation site or serve it for preview.

```sh
make docs-build
make docs-serve
```

--------------------------------

### Preview Documentation Locally

Source: https://github.com/kenn-io/kata/blob/main/docs/development/contributing.md

Serve the documentation site locally for preview. Note that this server is for local use only; published files should be hosted on a real static host.

```sh
make docs-serve
```

--------------------------------

### Build Kata from Source on Windows

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/install.md

Clone the Kata repository and use 'go build' to compile the executable. The binary is placed in the current directory.

```powershell
git clone https://github.com/kenn-io/kata.git
cd kata
go build -o kata.exe ./cmd/kata
```

--------------------------------

### Initialize kata Project

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/quickstart.md

Navigates to your repository and initializes kata for project tracking. This command sets up kata within your project directory.

```sh
cd your-repo
kata init
```

--------------------------------

### Initialize Kata Workspace

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/quickstart.md

Use this command to create a `.kata.toml` file for project binding. It's recommended to commit this file for consistent project resolution across different environments.

```sh
kata init
```

--------------------------------

### Build Documentation Site

Source: https://github.com/kenn-io/kata/blob/main/docs/development/contributing.md

Build the static documentation site using Zensical. This command checks for errors and prepares the site for deployment.

```sh
make docs-check
```

--------------------------------

### List Projects

Source: https://github.com/kenn-io/kata/blob/main/docs/reference/cli.md

List all available projects.

```sh
kata projects list
```

--------------------------------

### Pull Embedding Model with Ollama

Source: https://github.com/kenn-io/kata/blob/main/docs/guide/semantic-search.md

Install Ollama and pull an embedding model to run a local embeddings endpoint.

```sh
ollama pull nomic-embed-text
```

--------------------------------

### Find Ready Work

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/quickstart.md

Use `kata ready` to list open issues that are not blocked by any other open issues. Options like `--unowned`, `--label`, and `--no-label` can filter the results.

```sh
kata ready
kata ready --unowned
kata ready --label backend --no-label blocked
```

--------------------------------

### Check for Kata Updates

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/install.md

Run this command after installation to check if a newer version of Kata is available on GitHub releases.

```sh
kata update --check
```

--------------------------------

### Enroll Project into Federation Hub

Source: https://github.com/kenn-io/kata/blob/main/docs/reference/cli.md

Enroll a project into a federation hub. This command sends an enrollment API call to the hub URL, creating the project on the hub if it doesn't exist, enabling federation, and creating the enrollment. Use `--allow-insecure` if necessary. The `--adopt-existing` flag is used when adopting a differently named spoke project.

```sh
kata federation enroll --project <project> --spoke-instance <uid> --hub-url <url> --actor <actor> [--allow-insecure]
```

```sh
kata federation enroll --adopt-existing
```

--------------------------------

### Kata local override configuration file

Source: https://github.com/kenn-io/kata/blob/main/docs/guide/workspaces-projects.md

Example of the `.kata.local.toml` file, which is ignored by Git and used for per-machine settings such as routing to a remote daemon.

```toml
version = 1

[server]
url = "http://100.64.0.5:7777"
```

--------------------------------

### Configure Client to Connect to Remote Daemon

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/remote-daemon.md

Set environment variables to point clients to the remote daemon's URL and provide the authentication token. This is the primary method for client configuration.

```sh
export KATA_SERVER=http://100.64.0.5:7777
export KATA_AUTH_TOKEN=change-me
kata list
```

--------------------------------

### Get Spoke Instance Identity

Source: https://github.com/kenn-io/kata/blob/main/docs/design/federation.md

Retrieve the unique identifier for the current spoke instance. This UID is required when creating an enrollment token on the hub.

```bash
kata federation identity
```

--------------------------------

### Initialize and Manage Issues with Kata CLI

Source: https://github.com/kenn-io/kata/blob/main/README.md

Basic commands to initialize a workspace, create new issues, list open work, show issue details, and interact with the TUI. Use the short ID generated by 'kata create' for subsequent commands.

```sh
cd your-repo
kata init                              # bind this workspace to a kata project
kata create "fix login race"           # prints a short id, e.g. abc4
kata list                              # see open work
kata show abc4                         # inspect by short id
kata tui                               # browse and triage interactively
```

--------------------------------

### Join Existing Project to Federation Hub

Source: https://github.com/kenn-io/kata/blob/main/docs/design/federation.md

Joins an existing project to a federation hub, adopting the existing project. Requires hub URL, hub project ID, and token. Supports push mode.

```bash
kata federation join --project <existing-project> --hub-url <url> --hub-project-id <id> \
  --token <token> --actor <actor> --push --adopt-existing
```

--------------------------------

### List Tasks with JSON Output

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/quickstart.md

Use the `--json` flag to get the full response in JSON format, which is ideal for scripting and further processing with tools like `jq`.

```sh
kata list --json | jq .
```

--------------------------------

### Get Spoke Instance UID

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/federation.md

Retrieve the unique identifier for the spoke instance from the spoke daemon. Ensure commands target the spoke daemon by setting KATA_SERVER or leaving it unset for local spokes.

```sh
cd <spoke-worktree>
kata federation identity
```

--------------------------------

### Deploy Docs Project (CLI)

Source: https://github.com/kenn-io/kata/blob/main/docs/development/deploying-docs.md

Shell script to deploy the current committed workspace to production. It regenerates assets, builds docs, runs checks, and deploys via Vercel.

```sh
scripts/update-docs.sh
```

--------------------------------

### Migrate Beads Project to Kata

Source: https://github.com/kenn-io/kata/blob/main/docs/guide/migrating-from-beads.md

Run this command from the directory containing your Beads project to initiate the import process. Ensure you have initialized a Kata project first.

```bash
cd your-repo            # the workspace with the .beads database
kata init              # bind a kata project, if you have not already
kata import --source-format beads
```

--------------------------------

### Multiline Text and Comments in Fenced Blocks

Source: https://github.com/kenn-io/kata/blob/main/docs/reference/agent-output.md

This example demonstrates how multiline text and comments are preserved within fenced `text` blocks. The `text` info string indicates that the content should be treated as plain text, including nested code blocks.

```text
OK show abc4
Issue: abc4 "Fix login race"
Status: open
Body:
```text
Safari can double-submit the callback.
```
```

--------------------------------

### Initialize Workspace

Source: https://github.com/kenn-io/kata/blob/main/docs/reference/cli.md

Initializes the workspace by writing the secret-free .kata.toml binding. Use --project to specify the project name explicitly. Pass --with-agents to add or refresh kata's guidance block for coding agents.

```sh
kata init [--project <name>] [--with-agents]
cata init [--replace | --reassign]
```

--------------------------------

### Enable Federation for a Project

Source: https://github.com/kenn-io/kata/blob/main/docs/design/federation.md

Explicitly enable federation for an existing project. This records necessary metadata and baseline events for federation. It's optional if the next step is enrollment, as enrollment can auto-enable the project.

```bash
kata federation enable --project fedlab
```

--------------------------------

### Create Child Work and Manage Relationships

Source: https://github.com/kenn-io/kata/blob/main/docs/workflows/agents.md

Create child work under a parent issue and connect ordering using `--blocks` or `--blocked-by`. Use `--related` for context.

```sh
kata create "docs: rewrite CLI reference" --parent y04r --agent
```

```sh
kata edit cli-ref --blocked-by scaffold --agent
```

--------------------------------

### Import Project Data

Source: https://github.com/kenn-io/kata/blob/main/docs/reference/cli.md

Use `kata import` to restore project data from a backup. Specify the input and target paths. The `--force` flag can be used to overwrite existing data. The `--source-format beads` option is for importing data from the 'beads' format, which merges into the current project using the `bd` CLI.

```sh
kata import --input PATH --target PATH [--force]
```

```sh
kata import --source-format beads
```

--------------------------------

### Versioned Backups with Git

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/backup-restore.md

Implement a versioned backup workflow by initializing a Git repository, exporting the database, and committing the snapshot. This allows for easy tracking of database changes over time.

```sh
mkdir -p ~/kata-backups
cd ~/kata-backups
git init -q
kata daemon stop
kata export --output snapshot.jsonl
kata daemon start
git add snapshot.jsonl
git commit -q -m "snapshot $(date -u +%FT%TZ)"
```

--------------------------------

### Join a Federation Hub

Source: https://github.com/kenn-io/kata/blob/main/docs/reference/cli.md

Join a project to a federation hub. This command requires the hub URL, hub project ID, and an actor token. The `--push` flag enables push operations. Use `--adopt-existing` to join an already existing project.

```sh
kata federation join --project <project> --hub-url <url> --hub-project-id <id> --token <token> --actor <actor> [--push]
```

```sh
kata federation join --project <existing-project> --hub-url <url> --hub-project-id <id> --token <token> --actor <actor> --push --adopt-existing
```

--------------------------------

### Initialize Kata Workspace with Agent Guidance

Source: https://github.com/kenn-io/kata/blob/main/README.md

Initializes a Kata workspace and optionally writes managed Kata briefing into agent guidance files. This command refreshes existing AGENTS.md and CLAUDE.md files or creates AGENTS.md if it doesn't exist, without overwriting other content.

```sh
kata init --with-agents
```

--------------------------------

### Enroll a Spoke Project

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/federation.md

Create an enrollment for a trusted spoke. The `--hub-url` selects the hub daemon, and authentication is handled via `KATA_AUTH_TOKEN` or `[auth].token`.

```sh
export KATA_AUTH_TOKEN=<personal-identity-token>
kata federation enroll --project fedlab \
  --spoke-instance 01H... \
  --hub-url http://100.64.0.5:7787 \
  --actor wesm
```

--------------------------------

### Show Project Details

Source: https://github.com/kenn-io/kata/blob/main/docs/reference/cli.md

Display detailed information about a specific project.

```sh
kata projects show <project>
```

--------------------------------

### Join a Federated Project from Spoke

Source: https://github.com/kenn-io/kata/blob/main/docs/design/federation.md

Execute this command on the spoke to join a federated project using the enrollment token generated by the hub. It fetches project details from the hub and configures the spoke. The `--push` flag enables push mode.

```bash
kata federation join --project fedlab \
  --hub-url http://<private-hub-ip>:7787 \
  --hub-project-id 1 \
  --token ... \
  --actor wesm \
  --push
```

--------------------------------

### Enroll in Federation

Source: https://github.com/kenn-io/kata/blob/main/docs/design/federation.md

Enrolls a spoke instance into the federation hub. Requires project, spoke instance UID, hub URL, and actor. Optionally allows insecure connections.

```bash
kata federation enroll --project <project> --spoke-instance <uid> --hub-url <url> \
  --actor <actor> [--allow-insecure]
```

--------------------------------

### Enable Federation

Source: https://github.com/kenn-io/kata/blob/main/docs/design/federation.md

Enables federation for a specific project. Requires the project identifier.

```bash
kata federation enable --project <project>
```

--------------------------------

### Enroll Spoke Project in Hub

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/federation.md

Create a hub enrollment for a spoke project. This command reaches the hub using --hub-url and requires the hub API token via KATA_AUTH_TOKEN. If the hub project does not exist, it will be created.

```sh
export KATA_AUTH_TOKEN=<personal-identity-token>

kata federation enroll --project <hub-project> \
  --spoke-instance <spoke-instance-uid> \
  --hub-url <hub-api-url> \
  --actor <actor>
```

--------------------------------

### Manage Identity Tokens (CLI)

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/remote-daemon.md

Manage database-backed tokens for stable per-user attribution. This includes creating, listing, and revoking tokens using the Kata CLI.

```sh
export KATA_AUTH_TOKEN=bootstrap-admin-token
kata tokens create --actor wesm --name laptop
kata tokens list
kata tokens revoke 1
```

--------------------------------

### Enroll a Spoke Instance

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/federation.md

Enrolls a spoke instance into the federation. This command can create the project on the hub if it doesn't exist and allows for insecure connections.

```sh
kata federation enroll --project <project> --spoke-instance <uid> --hub-url <url> \
  --actor <actor> [--allow-insecure]
```

```sh
kata federation enroll --project <project> --spoke-instance <uid> \
  --hub-url <http-hostname-url> --actor <actor> --allow-insecure
```

--------------------------------

### Enable GitHub Sync for Enterprise Hosts

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/github-sync.md

Configure GitHub sync for GitHub Enterprise instances. This requires setting the allowed hosts and specifying the enterprise host during enablement.

```sh
export KATA_GITHUB_SYNC_ALLOWED_HOSTS=github.example
kata sync github enable \
  --host github.example \
  --repo example-org/example-repo \
  --interval 24h
```

--------------------------------

### Adopt Existing Project into Federation

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/federation.md

Use this command to adopt an existing non-federated project into the hub. This requires an enrollment token with adoption enabled and the '--adopt-existing' flag. Adoption preserves issue states but not the pre-adoption event timeline.

```sh
kata federation join --project fedlab \
  --hub-url http://100.64.0.5:7787 \
  --hub-project-id 1 \
  --token ... \
  --actor wesm \
  --push \
  --adopt-existing
```

--------------------------------

### Create and Inspect Issues

Source: https://github.com/kenn-io/kata/blob/main/docs/get-started/quickstart.md

Use `kata create` to make new issues with details like body, labels, owner, and priority. `kata list`, `kata show`, and `kata comment` are used for managing and interacting with existing issues.

```sh
kata create "fix login race" \
  --body "Safari can double-submit the callback." \
  --label auth \
  --owner alice \
  --priority 1

kata list
kata show abc4
kata comment abc4 --body "Reproduced on macOS."
```

--------------------------------

### Enable GitHub Sync with GitHub Enterprise

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/github-sync.md

Configure synchronization for a GitHub Enterprise instance by specifying the --host flag along with the repository and interval.

```sh
kata sync github enable \
  --host github.example \
  --repo example-org/example-repo \
  --interval 10m
```

--------------------------------

### Join Hub with Spoke Project

Source: https://github.com/kenn-io/kata/blob/main/docs/operations/federation.md

Join the spoke project to the hub using the enrollment token. This command targets the spoke daemon. Use --adopt-existing if the hub project already exists.

```sh
cd <spoke-worktree>

kata federation join --project <spoke-project> \
  --hub-url <hub-api-url> \
  --hub-project-id <hub-project-id> \
  --token <enrollment-token> \
  --capabilities pull,push,lease \
  --actor <actor> \
  --push \
  --adopt-existing
```