Commands & Options

The @houching/ag-kit CLI manages the installation, maintenance, and validation of the .agents/ runtime inside your project repository.

---

Commands

ag-kit init

Initializes AG Kit in the current working directory, writing the .agents folder and manifest.json.

agent-session

$

bunx ag-kit init

✔ Initialized AG Kit runtime

Created .agents/ (30 agents, 40 skills, 10 workflows)

Created manifest.json & manifest.lock.json

Behavior

• • Writes default agent definitions and instructions to .agents/
• • Creates manifest.json and manifest.lock.json
• • Fails safely if .agents/ already exists, unless –force is passed

---

ag-kit update

Updates an existing .agents directory with the latest toolkit definitions.

agent-session

$

bunx ag-kit update

⚠️

Direct Modification Notice

Modifying kit-managed files directly may cause update conflicts. Use local overrides or custom agent definitions where possible.

Behavior

• • Automatically creates a pre-update backup in .agents/.ag-kit/backups/
• • Uses the merge strategy by default: preserves local user modifications and writes incoming conflicting copies to .agents/.ag-kit/conflicts/
• • Supports –strategy replace for clean upstream alignment

---

ag-kit rollback

Restores .agents/ to a previous state from an automatic backup.

agent-session

$

bunx ag-kit rollback

? Restore backup 2026-07-26T16-03-21? (y/N) y

Restored backup 2026-07-26T16-03-21

Pre-rollback backup: .agents/.ag-kit/backups/…

Behavior

• • Lists available backups created during previous init or update operations
• • Prompts for confirmation before restoring files
• • Creates a backup of the current state before rolling back

---

ag-kit status

Displays the current status of the AG Kit installation, including version, modified files, and integrity check.

agent-session

$

bunx ag-kit status

Version: 1.0.0

Managed files: 142 total, 0 modified

Backups: 2 available in .agents/.ag-kit/backups/

Status: Clean

---

Options & Flags

Option	Description
-f, --force	Force overwrite of existing .agents directory during init or update.
-p, --path <dir>	Target directory for installation (defaults to current working directory).
-b, --branch <name>	Git branch or tag to install from.
-q, --quiet	Suppress non-error output during execution.
--dry-run	Preview files that would be created, updated, or conflicted without writing to disk.
--strategy <merge|replace>	Strategy for handling updates: merge (default, preserves custom files) or replace (clean overwrite).
--no-backup	Skip creating an automatic backup before modifying files.
--conflict-report <file>	Path where the JSON conflict report should be written.

---

Common Examples

Force Reinstallation

bunx ag-kit init --force

Dry Run Update

bunx ag-kit update --dry-run

Replace Strategy Update

bunx ag-kit update --strategy replace

Restore a Specific Backup

bunx ag-kit rollback --backup 2026-07-26T16-03-21