@inspecto-dev/cli

The official command-line interface for Inspecto. This tool automates the process of detecting, planning, applying, and maintaining the Inspecto setup within your project.

Onboarding Flow

For agent-capable environments, the preferred setup path is structured and machine-readable:

1. inspecto detect --json
2. inspecto plan --json
3. inspecto apply
4. inspecto doctor --json

See the public onboarding contract for response shapes and field semantics: packages/docs/integrations/onboarding-contract.md

Assistant-specific onboarding entrypoints are documented in: packages/docs/integrations/onboarding-skills.md

Use inspecto init when you want a guided manual setup in the terminal, or when the structured flow is not available.

Installation

You can use the CLI without installing it globally by using npx:

npx @inspecto-dev/cli <command>

Alternatively, you can install it as a dev dependency in your project:

npm install -D @inspecto-dev/cli

Commands

inspecto detect

Detects whether the current project can be onboarded automatically.

Features:

• Detects the package manager, build tool/framework, IDE, and available AI tools.
• Produces structured output for agent-driven setup flows.

inspecto plan

Previews the onboarding plan for the current project.

Features:

• Summarizes the proposed setup strategy and actions.
• Produces structured output that agents can inspect before applying changes.

inspecto apply

Applies the onboarding plan to the current project.

Features:

• Installs the required @inspecto-dev/plugin dependencies.
• Injects the plugin into supported build configurations.
• Installs or configures the selected IDE extension when needed.
• Writes .inspecto/settings.local.json and updates .gitignore when appropriate.

inspecto doctor

A diagnostic command to verify your current environment.

Features:

• Checks if the current project is a recognized framework/build tool.
• Verifies if the IDE is supported.
• Scans for available AI tools (both CLI and Plugin modes).
• Validates the current Inspecto installation and configuration.
• Supports --json for agent-friendly diagnostics.

inspecto init

The guided/manual fallback for scaffolding Inspecto into a project. It performs a comprehensive environmental analysis and automatically configures Inspecto in one step.

Features:

• Package Manager Detection: Auto-detects npm, pnpm, yarn, or bun.
• Build Tool / Framework Detection: Detects Vite, Webpack, Rspack, Rsbuild, and others. Supports legacy versions (e.g., @rspack/cli < 0.4.0).
• IDE Detection: Prioritizes environment variables, then falls back to directory structures to accurately detect VS Code, Cursor, Trae, Windsurf, or WebStorm.
• AI Tool Detection: Scans for both CLI-based tools (Claude, Coco, CodeX, Gemini) and IDE Plugins (GitHub Copilot, Claude Code, Gemini, CodeX).
• Interactive Prompts: If multiple build configurations or AI tools are detected, it presents an interactive prompt for you to select your preferred configuration.
• AST Injection: Safely injects the @inspecto-dev/plugin into your Vite configuration file (vite.config.ts, etc.) using AST transformation, preventing duplicate injections. Manual setup is required for other build tools.
• IDE Extension Installation: Uses a robust 4-level waterfall strategy to install the necessary IDE extension.
• Configuration Scaffolding: Generates the .inspecto/settings.local.json file tailored to your detected or selected AI tools, and updates .gitignore to prevent committing local settings.

inspecto teardown

A clean-up command to remove Inspecto from your project.

Features:

• Uninstalls @inspecto-dev/plugin and @inspecto-dev/cli.
• Provides manual instructions to remove the plugin from your build configuration file (AST removal is currently unsupported).
• Deletes the .inspecto directory and its contents.
• Restores .gitignore by removing Inspecto-specific rules.

Technical Details

Waterfall Degradation Strategy

The CLI employs a resilient fallback strategy for certain operations, such as installing IDE extensions.

IDE Extension Installation Levels:

1. PATH Command: Attempts to use the IDE's CLI command (e.g., code --install-extension).
2. Binary Path: Searches known default installation paths for the IDE binary across different operating systems (macOS, Linux, Windows).
3. URI Scheme: Uses the IDE's deep-link URI scheme (e.g., vscode:extension/inspecto...).
4. Manual: If all else fails, provides explicit instructions for the user to install the extension manually.

AI Tool Detection

The CLI intelligently detects AI tools across two modes:

• CLI Mode: Checks the system PATH for known executables (e.g., claude, coco).
• Plugin Mode: Checks the IDE's extension directories (e.g., ~/.vscode/extensions) for known plugin IDs.

When a tool supports both modes, the CLI merges the detections and presents a unified option to the user, configuring the settings.local.json accordingly.