CLI Reference¶

Installation¶

npm install -g @devran-ai/kit    # Global install
npx @devran-ai/kit <command>     # Or use npx

Commands¶

kit init¶

Install the .agent/ framework into your project.

kit init [options]

Flag	Description
`--force`	Overwrite existing `.agent/` (creates backup)
`--path <dir>`	Install to a specific directory
`--dry-run`	Preview changes without writing
`--quiet`	Suppress banner output
`--ide <name>`	Generate config for single IDE (`cursor`, `opencode`, `codex`)
`--skip-ide`	Skip IDE config generation

kit update¶

Non-destructive framework update. Preserves session data, decisions, and custom rules.

kit update [--dry-run]

kit status¶

Display project dashboard with agent counts, workflow state, and health metrics.

kit status

Alias: kit dashboard

kit verify¶

Validate manifest integrity — checks that all referenced files exist and counts match.

kit verify

kit scan¶

Run security scanner on .agent/ files. Detects injection patterns, hardcoded secrets, and anomalies.

kit scan

kit plugin¶

Manage third-party plugins.

kit plugin list              # List installed plugins
kit plugin install <path>    # Install plugin from directory
kit plugin remove <name>     # Remove installed plugin

kit market¶

Browse and install from the skill marketplace.

kit market search <query>    # Search marketplace plugins
kit market info <name>       # View plugin details
kit market install <name>    # Install from marketplace
kit market update            # Refresh registry index

kit heal¶

Auto-diagnose and generate fix patches for CI failures.

kit heal [--file <path>] [--apply]

Flag	Description
`--file <path>`	Path to CI log file
`--apply`	Apply patches (default is dry-run)

kit health¶

Aggregated health check across all subsystems (error budget, plugin integrity, config validation, self-healing).

kit health

kit sync-bot-commands¶

Sync .agent/workflows/ and .agent/commands/ descriptions to the Telegram Bot API menu.

kit sync-bot-commands [options]

Flag	Description
`--token <BOT_TOKEN>`	Telegram bot token (or set `TELEGRAM_BOT_TOKEN` env var)
`--dry-run`	Preview commands without pushing to Telegram
`--limit <N>`	Max commands to sync (1–100, default: all)
`--source <type>`	Source to scan: `workflows` (default), `commands`, or `both`
`--scope <type>`	Target single scope: `default`, `all_private_chats`, `all_group_chats`, `all_chat_administrators`. Omit to push to all scopes
`--clear`	Delete commands from scope(s) instead of pushing
`--guard`	Restore cached commands to `all_private_chats` scope (lightweight re-sync)
`--install-guard`	Install SessionStart hook in `~/.claude/settings.json` for automatic menu restoration

Reads frontmatter description from each workflow/command markdown file and formats them as Telegram bot menu commands. Priority tiers (critical, high, medium, low) determine ordering when the limit is reached.

When a workflow frontmatter includes an args field (e.g., args: "PR #"), the args hint is appended to the Telegram description: Review PR (+ PR #). This helps users know which commands accept arguments.

The Telegram plugin overwrites bot menu commands on every session start with its own defaults (/start, /help, /status). The guard system solves this permanently:

kit sync-bot-commands                  # Sync workflows + create cache
kit sync-bot-commands --install-guard  # Install SessionStart hook (one-time)

After installation, the guard runs automatically on every new Claude Code session:

SessionStart hook fires lib/telegram-menu-guard.js
Guard spawns a detached child process (non-blocking)
Child waits 8 seconds for the plugin to finish connecting
Reads cached commands from ~/.claude/channels/telegram/bot-menu-cache.json
Pushes the full menu (workflows + plugin base commands) to all_private_chats scope

The cache is auto-created on every successful sync-bot-commands run and merges plugin base commands (/start, /help) so they remain accessible.

Exit Codes¶

Code	Meaning
`0`	Success
`1`	Error (check stderr for details)