# ACK CLI

`ack` is the command-line tool for bootstrapping, updating, and managing **AckKit** projects — curated kits of Claude Code skills, agents, commands, and hooks.

[![npm](https://img.shields.io/npm/v/@chiendt/ack-cli.svg)](https://www.npmjs.com/package/@chiendt/ack-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

---

## What you get

- **One command to bootstrap** a Claude-ready project from a kit (engineer, QA, marketing).
- **Idempotent installs and updates** — your customizations are preserved across upgrades.
- **Web dashboard** for managing skills, agents, commands, and hooks (`ack config ui`).
- **Multi-provider migration** — move config between Claude Code, Cursor, Codex, Gemini CLI, and more.
- **Built-in doctor** with auto-fix for the most common setup problems.

## Installation

The CLI is published on npm at [`@chiendt/ack-cli`](https://www.npmjs.com/package/@chiendt/ack-cli). Pick one:

```bash
npm install -g @chiendt/ack-cli
pnpm add -g @chiendt/ack-cli
yarn global add @chiendt/ack-cli
bun  add -g @chiendt/ack-cli
```

Verify:

```bash
ack --version
```

> **Requirements:** Node.js ≥ 18, [GitHub CLI](https://cli.github.com/) (`gh`) for kit downloads.

## Authentication

AckKit kits live in private GitHub repos. Authenticate once with the GitHub CLI:

```bash
gh auth login
# choose: GitHub.com → HTTPS → Login with a web browser
```

> Don't use *"Paste an authentication token"* — OAuth via web browser is the supported path. The CLI reads `gh`'s token automatically; tokens are stored in your OS keychain.

## Quick start

```bash
# Bootstrap a new project from a kit
ack new --kit engineer

# Initialize / update an existing project
ack init

# Open the web dashboard
ack config

# Health check + auto-fix
ack doctor --fix
```

Run `ack --help` for the full command list, or `ack <command> --help` for any one. The full machine-readable command reference is at [`docs/cli-reference.md`](./docs/cli-reference.md).

## Available kits

| Kit         | Slash prefix | Repo                              | Description                                                |
|-------------|--------------|-----------------------------------|------------------------------------------------------------|
| `engineer`  | `/ck:`       | `chiendt1108/ack-engineer`        | Engineering toolkit for building with Claude               |
| `marketing` | `/mkt:`      | `chiendt1108/claudekit-marketing` | Content automation: campaigns, social, analytics           |
| `fqc-qa`    | `/fqc:`      | `chiendt1108/ack-fqc-qa`          | QA: test design, debugging, security, scenario coverage    |

Kits are sold as part of [AckKit](https://AckKit.cc). Use `ack versions --kit <name>` to see released versions.

## Common workflows

### Create a project

```bash
ack new                           # interactive
ack new --kit engineer --yes      # non-interactive
ack new --kit fqc-qa --prefix qa  # custom slash prefix → /qa:
```

### Update an existing project

```bash
ack init               # update to latest, preserve your customizations
ack init --fresh       # ⚠️ destructive: wipe and reinstall
```

`--fresh` is destructive. `--force` is **not** a fresh install — it only skips prompts.

### Update the CLI itself

```bash
ack update --check          # check for newer CLI
ack update                  # install latest stable
ack update --dev            # install latest @dev prerelease
```

### Health check

```bash
ack doctor              # full health check
ack doctor --fix        # auto-repair fixable issues
ack doctor --report     # generate a shareable gist
ack doctor --json       # machine-readable output
```

### Migrate config to another agent

```bash
ack migrate --dry-run   # preview the migration plan
ack migrate             # apply it (interactive conflict resolution)
```

Supported providers: Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Amp, Antigravity, OpenCode, OpenHands, Droid, Roo, Kilo. See [`docs/reconciliation-architecture.md`](./docs/reconciliation-architecture.md) for the RECONCILE → EXECUTE → REPORT design.

### Uninstall

```bash
ack uninstall            # interactive — pick scope and kits
ack uninstall --local    # remove project install only
ack uninstall --global   # remove ~/.claude install only
```

## Web dashboard

```bash
ack config              # http://localhost:3456
ack config --host 0.0.0.0   # expose on LAN
```

The dashboard lets you browse and toggle skills, agents, commands, and hooks; inspect recent Claude hook activity; and run migrations interactively.

## Per-project layout

Override where a kit installs files via `package.json`:

```json
{
  "ack": {
    "sourceDir": ".claude",
    "runtimeDir": ".claude"
  }
}
```

## Protected files

The following are never overwritten by `ack init` or updates:

- `.env`, `.env.local`, `.env.*.local`
- `*.key`, `*.pem`, `*.p12`
- `node_modules/**`, `.git/**`, `dist/**`, `build/**`

Add your own patterns with `--exclude`:

```bash
ack init --exclude "*.log" --exclude "vendor/**"
```

## Development

```bash
git clone https://github.com/chiendt1108/ack-cli.git
cd ack-cli
bun install
bun run dev new --kit engineer    # run locally without installing globally
bun test
bun run ci:local                  # full quality gate (matches GitHub Actions)
```

See [`CLAUDE.md`](./CLAUDE.md) for the contributor guide, [`docs/codebase-summary.md`](./docs/codebase-summary.md) for architecture, and [`docs/code-standards.md`](./docs/code-standards.md) for conventions.

## Documentation

| Doc | Topic |
|-----|-------|
| [`docs/cli-reference.md`](./docs/cli-reference.md)                       | Full command + flag reference |
| [`docs/codebase-summary.md`](./docs/codebase-summary.md)                 | Architecture & module map |
| [`docs/system-architecture.md`](./docs/system-architecture.md)           | Design diagrams, data flow |
| [`docs/reconciliation-architecture.md`](./docs/reconciliation-architecture.md) | `ack migrate` internals |
| [`docs/deployment-guide.md`](./docs/deployment-guide.md)                 | Release & publishing |
| [`docs/project-roadmap.md`](./docs/project-roadmap.md)                   | Roadmap & release timeline |

## Troubleshooting

| Symptom | First step |
|---------|------------|
| `Access denied` / kit download fails              | `ack doctor --fix` |
| `GitHub CLI not authenticated`                    | `gh auth login` (web browser flow) |
| Module / dependency errors                        | `ack doctor --fix` |
| Want a sharable diagnostic                        | `ack doctor --report` |
| Skill not appearing after install                 | Check `~/.ack/projects.json`, then `ack config` |

## FAQ

**Do I need GitHub CLI?** Yes — `gh` is the only supported auth path; tokens are stored in your OS keychain.

**Can I use a Personal Access Token?** No. PAT-paste auth was removed. Use `gh auth login` with the web browser flow.

**Will updating overwrite my custom skills/commands?** No. Custom files in `.claude/` are detected (SHA-256 hash comparison) and preserved. Use `--fresh` if you want a clean reinstall.

**Where is my config stored?** `~/.ack/config.json`, with the GitHub token in the OS keychain. The projects registry is at `~/.ack/projects.json`.

**How do I get help?** `ack doctor --report` produces a shareable gist URL. Or open an issue at [github.com/chiendt1108/ack-cli/issues](https://github.com/chiendt1108/ack-cli/issues).

## License

[MIT](./LICENSE)
