AgentDock CLI

@cogito.ai/cli — Scaffold production-ready AI coding agent projects for humans, CI pipelines, and AI agents.

Quick Start

# Interactive mode (for humans)
npx @cogito.ai/cli init

# Headless mode (for CI / AI agents)
npx @cogito.ai/cli init --name my-app --template web-nextjs --pm pnpm --json

# Workspace-member mode (existing pnpm workspace)
npx @cogito.ai/cli init --name my-app --template web-tanstackstart --dir apps/my-app --mode workspace --json

# Start MCP Stdio server (for AI agents via Model Context Protocol)
npx @cogito.ai/cli mcp

Installation

# Run without installing (recommended)
npx @cogito.ai/cli <command>

# Global install
npm install -g @cogito.ai/cli
pnpm add -g @cogito.ai/cli

Commands

agentdock init

Scaffold a new project from a template. Auto-detects the environment:

• TTY → interactive prompts (human mode)
• Non-TTY / --silent / --json → headless execution (agent/CI mode)

--mode auto detects the nearest pnpm workspace and checks whether the target matches its packages globs. Workspace-member output does not copy pnpm-workspace.yaml, pnpm-lock.yaml, or .npmrc, and removes the member packageManager / engines.pnpm fields. Root allowBuilds changes are returned in requiredRootChanges; the CLI does not modify the root configuration.

JSON output (success):

{
  "ok": true,
  "targetDir": "/path/to/my-app",
  "name": "my-app",
  "template": "web-nextjs",
  "mode": "standalone",
  "integrations": ["mastra"],
  "lockfileOwner": "/path/to/my-app/pnpm-lock.yaml",
  "requiredRootChanges": [],
  "rootConfigConflicts": []
}

JSON output (failure):

{
  "ok": false,
  "error": "TARGET_DIR_EXISTS",
  "message": "Directory already exists: /path/to/my-app"
}

Error codes: MISSING_ARG · TEMPLATE_NOT_FOUND · TARGET_DIR_EXISTS · CLI_VERSION_OUTDATED · SCAFFOLD_FAILED · INVALID_MODE · WORKSPACE_MODE_UNSUPPORTED · WORKSPACE_NOT_MATCHED · WORKSPACE_STANDALONE_CONFLICT · WORKSPACE_CONFIG_INVALID · WORKSPACE_PACKAGE_MANAGER_INCOMPATIBLE · WORKSPACE_NODE_INCOMPATIBLE · INVALID_INTEGRATION · INTEGRATION_NOT_SUPPORTED · INTEGRATION_CONFLICT

agentdock mcp

Start an MCP (Model Context Protocol) Stdio server. Exposes CLI capabilities as tools directly callable by AI agents.

agentdock mcp

Available tools:

VS Code Copilot MCP config (.vscode/mcp.json):

{
  "servers": {
    "agentdock": {
      "type": "stdio",
      "command": "npx",
      "args": ["@cogito.ai/cli", "mcp"]
    }
  }
}

Available Templates

Architecture

The CLI uses an Adapter pattern — a single executor core serves three consumer surfaces:

agentdock init
      │
      ├── TTY detected ──→ Human Adapter  (Clack interactive UI)
      └── Non-TTY / flags ──→ Agent Adapter (structured JSON output)

agentdock mcp ──→ MCP Adapter (MCP Stdio Server)

All adapters share the same Core Executor (scaffold + registry)

Design principles:

1. Headless-first — the executor core has no TTY dependency; the human UI is a thin shell on top.
2. Structured output as protocol — --json mode produces stable machine-parseable NDJSON, not natural language.
3. One capability, three surfaces — scaffold_project is implemented once and projected to CLI flags, JSON mode, and MCP tool automatically.

Tech stack:

Development

# Install dependencies
pnpm install

# Regenerate template registry
pnpm --filter @cogito.ai/cli generate-registry

# Run from source (no build needed)
npx tsx packages/cli/bin/agentdock.ts init

# Run tests
pnpm --filter @cogito.ai/cli test

# Build
pnpm --filter @cogito.ai/cli build

Adding a template

1. Create templates/<id>/ with a complete project structure.
2. Add package.json with "agentdock": { "minCliVersion": "x.y.z" }.
3. Run pnpm --filter @cogito.ai/cli generate-registry.
4. Publish a new CLI version — templates are bundled inside the npm package.

Single-package templates that should support embedding in a pnpm workspace can add agentdock.workspaceMember.rootAllowBuilds. Monorepo templates should remain standalone-only.

Templates that support a pnpm range without an exact packageManager pin can set agentdock.packageManagerEnforced: true and declare engines.pnpm. This keeps init pnpm-only while avoiding automatic package-manager switching.

Publishing a new version

pnpm changeset          # describe the change
pnpm changeset version  # bump version + update CHANGELOG
pnpm --filter @cogito.ai/cli build
pnpm --filter @cogito.ai/cli publish

License

MIT

中文文档 →