npm package: @kitnai/cli
Description: CLI for installing AI agent components from the kitn registry
Latest version: 0.1.45

# @kitnai/cli

CLI for installing AI agent components from kitn registries.

## Installation

```bash
# Run directly with npx
npx @kitnai/cli init

# Or install globally
npm install -g @kitnai/cli
kitn init
```

Works with any package manager:

```bash
bunx @kitnai/cli init
pnpm dlx @kitnai/cli init
```

## Commands

### `kitn new [name]`

Create a new kitn project from a starter template. Scaffolds project files, initializes kitn, and installs dependencies.

```bash
# Interactive (prompts for name, framework, runtime, provider)
kitn new

# Non-interactive
kitn new my-app --runtime bun --provider openrouter -y

# Use a custom GitHub template
kitn new my-app --template github:user/repo

# Scaffold in the current directory
kitn new .
```

**Flags:**

| Flag | Description |
|------|-------------|
| `-f, --framework <framework>` | Template to use (`hono`) |
| `-t, --template <url>` | Custom template (`github:user/repo`) |
| `-r, --runtime <runtime>` | Runtime to use (`bun`, `node`, `deno`) |
| `-p, --provider <provider>` | AI provider (`openrouter`, `openai`, `anthropic`, `google`) |
| `-y, --yes` | Accept all defaults without prompting |

### `kitn init`

Initialize kitn in an existing project. Creates `kitn.json`, installs the core engine and adapter routes, and sets up tsconfig path aliases.

```bash
# Interactive (prompts for runtime, framework, and base directory)
kitn init

# Non-interactive with flags
kitn init --runtime bun --framework hono --base src/ai

# Accept all defaults (runtime=bun, framework=hono, base=src/ai)
kitn init -y
```

**Flags:**

| Flag | Description |
|------|-------------|
| `-r, --runtime <runtime>` | Runtime to use (`bun`, `node`, `deno`) — skips runtime prompt |
| `-f, --framework <framework>` | HTTP framework (`hono`, `hono-openapi`, `elysia`) — skips framework prompt |
| `-b, --base <path>` | Base directory for components (default: `src/ai`) — skips path prompt |
| `-y, --yes` | Accept all defaults without prompting |

When flags are provided, the corresponding prompts are skipped. This enables scripting and CI usage.

After setup, the CLI automatically installs the core engine and HTTP routes into your project.

### `kitn add [components...]`

Add components from a registry. Resolves `registryDependencies` transitively.

```bash
# Add a single component
kitn add weather-agent

# Add multiple components
kitn add weather-agent hackernews-tool eli5

# Add from a third-party registry
kitn add @acme/custom-agent

# Add a specific version
kitn add weather-agent@1.2.0

# Overwrite existing files without prompting
kitn add weather-agent --overwrite

# Type-first syntax — specify the type before the name
kitn add agent weather
kitn add tool weather

# Filter by type with the --type flag
kitn add --type agent weather
```

Components from the default `@kitn` registry don't need a namespace prefix. Components from other registries use `@namespace/name` format.

When multiple components share the same name but differ in type (e.g., a `weather` agent and a `weather` tool), you'll be prompted to choose which to install. Use the type-first syntax or `--type` flag to skip the prompt.

Third-party components install into a namespace subdirectory (e.g. `src/ai/agents/acme/custom-agent.ts`).

**Flags:**

| Flag | Description |
|------|-------------|
| `-o, --overwrite` | Overwrite existing files without prompting |
| `-t, --type <type>` | Filter by component type during resolution |
| `-y, --yes` | Skip confirmation prompt |

When a file already exists and differs from the registry version, you'll see a unified diff and be prompted to keep your version or overwrite.

After installation, the CLI:
- Installs npm dependencies via your detected package manager
- Checks for missing environment variables
- Shows post-install documentation

### `kitn list`

List available and installed components from configured registries.

```bash
# List all components from all registries
kitn list

# Filter by type
kitn list agents
kitn list --type tool

# Only show installed components
kitn list --installed

# Filter by registry
kitn list --registry @acme

# Show version numbers
kitn list --verbose
```

**Flags:**

| Flag | Description |
|------|-------------|
| `-i, --installed` | Only show installed components |
| `-t, --type <type>` | Filter by type (`agent`, `tool`, `skill`, `storage`, `package`, `cron`) |
| `-r, --registry <namespace>` | Only show components from this registry |
| `-v, --verbose` | Show version numbers |

### `kitn diff <component>`

Show differences between your local version and the current registry version.

```bash
kitn diff weather-agent
```

Outputs a unified diff for each file in the component. Shows "up to date" if there are no differences.

### `kitn remove [component]`

Remove an installed component. Deletes files and removes tracking from `kitn.lock`.

```bash
# Remove a specific component
kitn remove weather-agent

# Interactive — pick from installed components
kitn remove
```

Prompts for confirmation before deleting files. Also aliased as `kitn uninstall`.

### `kitn update [components...]`

Update installed components to the latest registry version.

```bash
# Update specific components
kitn update weather-agent weather-tool

# Update all installed components
kitn update
```

Re-fetches components from the registry and applies the same conflict resolution as `kitn add --overwrite`.

### `kitn install`

Install components from `kitn.lock` at their exact recorded versions (like `npm ci`). Useful for fresh clones and CI.

```bash
# Install all locked components
kitn install

# Fail if lock file is inconsistent (CI mode)
kitn install --frozen
```

**Flags:**

| Flag | Description |
|------|-------------|
| `--frozen` | Fail if lock file is inconsistent or local files differ (for CI) |

### `kitn search <query>`

Search configured registries for components by name or description.

```bash
# Search for components
kitn search weather

# Filter by type
kitn search agent --type tool
```

**Flags:**

| Flag | Description |
|------|-------------|
| `-t, --type <type>` | Filter by component type |

### `kitn outdated`

Show installed components with newer versions available in the registry.

```bash
kitn outdated
```

Prints a table of installed vs. latest versions and tells you how many are outdated.

### `kitn tree`

Show the dependency tree of installed components.

```bash
kitn tree
```

Displays a visual tree with component types and deduplication markers.

### `kitn why <component>`

Explain why a component is installed by tracing its reverse dependency chain.

```bash
kitn why core
```

Shows whether the component is a top-level install or a transitive dependency, and prints the full dependency chain(s).

### `kitn doctor`

Check project integrity -- files, content hashes, dependencies, and orphans.

```bash
kitn doctor
```

Runs a series of health checks and reports pass/warn/fail status for each.

### `kitn try [name]`

Interactively test a tool or agent from your project.

```bash
# Pick a tool or agent interactively
kitn try

# Run a specific tool or agent by name
kitn try weather
```

For tools, prompts for input parameters and displays the result. For agents, starts a chat session where you can send messages and see tool calls and responses.

### `kitn info <component>`

Show details about a component from the registry.

```bash
# Default registry
kitn info weather-agent

# With namespace and version
kitn info @acme/tool@1.0.0
```

Displays the component's description, type, version, dependencies, files, and changelog.

### `kitn create <type> <name>`

Scaffold a new kitn component. Valid types: `agent`, `tool`, `skill`, `storage`, `cron`.

```bash
kitn create agent my-agent
kitn create tool my-tool
kitn create cron my-cron
```

Creates a new component file with a template and wires it into the barrel file (`src/ai/index.ts`).

### `kitn link`

Wire a tool into an agent's `tools` object. Adds the import statement and tools entry automatically.

```bash
# Fully explicit
kitn link tool weather --to general-agent

# With a custom key name
kitn link tool weather --to general-agent --as getWeather

# Interactive — pick tool, then agent
kitn link
```

**Flags:**

| Flag | Description |
|------|-------------|
| `--to <agent>` | Target agent name (interactive if omitted) |
| `--as <key>` | Key name in the tools object (defaults to the export name) |

### `kitn unlink`

Remove a tool from an agent's `tools` object. Removes the import if it's no longer referenced.

```bash
# Fully explicit
kitn unlink tool weather --from general-agent

# Interactive — pick tool, then agent
kitn unlink
```

**Flags:**

| Flag | Description |
|------|-------------|
| `--from <agent>` | Target agent name (interactive if omitted) |

### `kitn rules`

Generate or regenerate AI coding assistant rules files (e.g. `AGENTS.md`, `.cursor/rules/kitn.mdc`).

```bash
kitn rules
```

Prompts you to select which AI coding tools you use, then fetches the latest rules template from the registry and generates the corresponding files. Works in any directory — uses project aliases from `kitn.json` if available, otherwise uses defaults.

### `kitn check`

Check for CLI updates.

```bash
kitn check
```

Shows the current version and whether a newer version is available on npm.

### `kitn registry`

Manage component registries.

```bash
# Add a registry with metadata
kitn registry add @acme https://acme.dev/r/{type}/{name}.json \
  --homepage https://acme.dev \
  --description "Acme AI components"

# Add a plain registry (URL only)
kitn registry add @myteam https://registry.myteam.dev/r/{type}/{name}.json

# List configured registries (shows URL, homepage, description)
kitn registry list

# Remove a registry
kitn registry remove @myteam

# Overwrite an existing registry
kitn registry add @myteam https://new-url.dev/r/{type}/{name}.json --overwrite

# Remove the default @kitn registry (requires --force)
kitn registry remove @kitn --force
```

**Subcommands:**

| Subcommand | Description |
|------------|-------------|
| `add <namespace> <url>` | Add a registry. Options: `-o` overwrite, `--homepage`, `--description` |
| `list` | List all configured registries with URLs and metadata |
| `remove <namespace>` | Remove a registry. `-f` required to remove `@kitn` |

The URL template uses `{type}` and `{name}` placeholders. Components are fetched by replacing these with the component's type directory (`agents`, `tools`, `skills`, `storage`, `package`) and name. The registry index is fetched by replacing `{type}/{name}.json` with `registry.json`.

## Configuration

### `kitn.json`

Created by `kitn init`. Controls where components are installed and which registries to use.

```json
{
  "$schema": "https://kitn.dev/schema/config.json",
  "runtime": "bun",
  "framework": "hono",
  "aliases": {
    "base": "src/ai",
    "agents": "src/ai/agents",
    "tools": "src/ai/tools",
    "skills": "src/ai/skills",
    "storage": "src/ai/storage"
  },
  "registries": {
    "@kitn": {
      "url": "https://kitn-ai.github.io/kitn/r/{type}/{name}.json",
      "homepage": "https://kitn.ai",
      "description": "Official kitn AI agent components"
    }
  }
}
```

| Field | Description |
|-------|-------------|
| `runtime` | `bun`, `node`, or `deno` |
| `framework` | `hono`, `hono-openapi`, or `elysia` |
| `aliases` | Directory paths for each component type |
| `registries` | Named registries — each value is a URL string or an object with `url`, `homepage`, `description` |

> Installed component tracking (file paths, content hashes, versions) is stored separately in `kitn.lock`. This file is auto-managed — don't edit it manually.

### Registry entries

Registry entries can be a plain URL string or a rich object:

```json
{
  "registries": {
    "@kitn": {
      "url": "https://kitn-ai.github.io/kitn/r/{type}/{name}.json",
      "homepage": "https://kitn.ai",
      "description": "Official kitn AI agent components"
    },
    "@myteam": "https://registry.myteam.dev/r/{type}/{name}.json"
  }
}
```

Both formats are supported. The CLI stores a rich object when `--homepage` or `--description` is provided, and a plain string otherwise.

## Package Manager Detection

The CLI automatically detects your package manager by checking for lockfiles in this order:

1. `bun.lock` / `bun.lockb` → bun
2. `pnpm-lock.yaml` → pnpm
3. `yarn.lock` → yarn
4. `package-lock.json` → npm

## How It Works

Components are **source code**, not packages. `kitn add` copies TypeScript files directly into your project. You own the code and can modify it freely.

The CLI tracks what it installed in `kitn.lock`, storing file paths and content hashes. This enables `kitn diff` to detect local changes and `kitn update` to apply registry updates.

### Hosting your own registry

Any HTTP server that serves JSON files matching the registry schema can be a kitn registry. See the [registry documentation](https://github.com/kitn-ai/registry) for the schema specification and instructions on registering your registry in the public directory.