insights/insightscli.yaml

config:
    description: Unified developer experience for the Insights monorepo.
    commands_dir: tools/insightscli-commands/insightscli_commands
    # Imported once at startup to register precheck handlers, telemetry property
    # hooks, and post-command hooks. Keep these modules cheap to import — heavy
    # dependencies must live behind lazy imports inside handler bodies.
    boot_modules:
        - insightscli_commands.prechecks
        - insightscli_commands.telemetry_props
        - insightscli_commands.hint_hook
    scripts_exclude:
        - mprocs.yaml
        - mprocs-test.yaml
        - sandbox-entrypoint.py
        - lint-feature-flag-sorting.mjs
        # Locally-built, gitignored binary (tools/phrocs). Referenced via cmd:/process
        # name, not bin_script:, so exclude it from auto-discovery to stop the manifest
        # regenerating a stub entry on every insightscli run.
        - phrocs
    env:
        files:
            - .env.development
            - .env.services
        secrets:
            file: .env.local
            marker: 'op://'
            wrap: [op, run, --env-file, '{file}', --]
    telemetry:
        # Write-only project token for Insights's internal insightscli project.
        # It cannot read data; safe to commit. Standalone insightscli users get a blank
        # default and telemetry stays disabled unless they set their own key.
        api_key: pk-JYFXrbqdzueOYb0wFUTnCglFKZuC4xRXBW790ewdcvn
        host: https://us.i.hanzo.ai

metadata:
    devbox:
        coder_url: https://coder.dev.insights.dev
    categories:
        - key: devenv
          title: Intent-based dev environment
        - key: core
          title: Core development commands
        - key: start
          title: Start services and background workers
        - key: health_checks
          title: Verify infrastructure readiness
        - key: migrations
          title: Database migrations
        - key: db
          title: Database operations
        - key: tests
          title: Run tests
        - key: quality
          title: Code quality and formatting
        - key: build
          title: Build and generate code
        - key: docker
          title: Docker-based service orchestration
        - key: deploy
          title: Deploy Insights to remote instances
        - key: auth
          title: Authenticate to internal services
        - key: tools
          title: Developer tools and utilities
        - key: desktop
          title: Desktop app (products/desktop)
        - key: devex
          title: Developer experience feedback
        - key: utilities
          title: Git worktrees and admin
        - key: devbox
          title: Remote development environment (devbox)
        - key: environment
          title: Environment and shell
    services:
        flox:
            name: Flox
            about: Manages reproducible development environments. All developers get the
                same exact versions of tools and dependencies.
        docker:
            name: Docker
            about: Isolates services and dependencies in containers to match production
                without requiring local installation. Orbstack strongly recommended over Docker
                Desktop.
        migration:
            name: Database migrations
            about: Schema updates and data migrations across PostgreSQL, Datastore, and
                async systems.
        datastore:
            name: Datastore
            about: Analytics database used for metrics, events, and funnel analysis throughout
                Insights.
        postgresql:
            name: PostgreSQL
            about: Primary relational database for application data, authentication, and
                feature flags.
        redis:
            name: Redis
            about: In-memory cache and queue backend for fast data access and job processing.
        kafka:
            name: Kafka
            about: Event streaming platform for reliable event processing and data pipelines.
        temporal:
            name: Temporal
            about: Workflow orchestration engine for reliable, long-running background jobs
                and retries.
        testing:
            name: Testing
            about: Automated test suites (unit, integration, E2E) to ensure code quality
                and prevent regressions.
        celery:
            name: Celery
            about: Distributed task queue for running background jobs like async exports,
                scheduled tasks, and email sending.
        nodejs:
            name: Node.js
            about: CDP workflows, session recordings, logs ingestion, and evaluation scheduler.
                Ingestion runs as a separate process (see ingestion unit).
        ingestion:
            name: Ingestion
            about: Event ingestion pipeline that processes incoming events and writes to
                Kafka (then Datastore). Runs as IngestionGeneralServer.
        django:
            name: Django
            about: Python web framework powering Insights's backend API, admin interface,
                and business logic.
        frontend:
            name: Frontend
            about: React-based web application providing Insights's user interface. Built
                with TypeScript, Vite, and Kea for state management.
        mprocs:
            name: mprocs
            about: Process orchestrator that runs all dev services in parallel with live
                output and easy process management.
        phrocs:
            name: phrocs
            about: Insights's custom process runner (replaces mprocs).
devbox:
    devbox:
        click: insightscli_commands.devbox.cli:devbox_help
        description: Show available devbox commands
    devbox:setup:
        click: insightscli_commands.devbox.cli:devbox_setup
        description: Install and configure local access to Coder devboxes
    devbox:doctor:
        click: insightscli_commands.devbox.cli:devbox_doctor
        description: Diagnose devbox prerequisites and setup (read-only)
    devbox:start:
        click: insightscli_commands.devbox.cli:devbox_start
        description: Start or create your remote devbox
    devbox:clone:
        click: insightscli_commands.devbox.cli:devbox_clone
        description: Clone a running devbox into a new one (carries full disk state)
    devbox:stop:
        click: insightscli_commands.devbox.cli:devbox_stop
        description: Stop your devbox (preserves disk, stops billing)
    devbox:restart:
        click: insightscli_commands.devbox.cli:devbox_restart
        description: Restart your devbox
    devbox:update:
        click: insightscli_commands.devbox.cli:devbox_update
        description: Update devbox to the latest template
    devbox:list:
        click: insightscli_commands.devbox.cli:devbox_list
        description: List your devboxes
    devbox:ssh:
        click: insightscli_commands.devbox.cli:devbox_ssh
        description: SSH into your devbox
        # exec-replaces the process (os.execvp): completed events can't fire
        untracked: true
    devbox:exec:
        click: insightscli_commands.devbox.cli:devbox_remote_exec
        description: Run a command inside your devbox (non-interactive)
        untracked: true
    devbox:open:
        click: insightscli_commands.devbox.cli:devbox_open
        description: Open devbox in browser, VS Code, or Cursor
        untracked: true
    devbox:logs:
        click: insightscli_commands.devbox.cli:devbox_logs
        description: Tail devbox build and agent logs
        # exec-replaces the process (os.execvp): completed events can't fire
        untracked: true
    devbox:destroy:
        click: insightscli_commands.devbox.cli:devbox_destroy
        description: Destroy your devbox and its data
    devbox:status:
        click: insightscli_commands.devbox.cli:devbox_status
        description: Show devbox status
    devbox:forward:
        click: insightscli_commands.devbox.cli:devbox_forward
        description: Forward Insights UI to localhost
        # exec-replaces the process (os.execvp): completed events can't fire
        untracked: true
    devbox:users:
        click: insightscli_commands.devbox.cli:devbox_users
        description: List Coder users (for devbox sharing)
    devbox:share:
        click: insightscli_commands.devbox.cli:devbox_share
        description: Share your devbox with other users
    devbox:unshare:
        click: insightscli_commands.devbox.cli:devbox_unshare
        description: Revoke access to your devbox from other users
    devbox:cleanup:disk:
        click: insightscli_commands.devbox.cli:devbox_cleanup_disk
        description: Free disk space by cleaning caches and build artifacts
    devbox:sync:
        click: insightscli_commands.devbox.sync:cmd_sync
        description: Mirror your local Insights checkout to a devbox
    devbox:task:
        click: insightscli_commands.devbox.cli:devbox_task
        description: Run a background agent task on a fresh devbox
        # exec-replaces the process (os.execvp): completed events can't fire
        untracked: true
    devbox:secret:list:
        click: insightscli_commands.devbox.cli:devbox_secret_list
        description: List your Coder user secrets
    devbox:secret:set:
        click: insightscli_commands.devbox.cli:devbox_secret_set
        description: Create or replace a Coder user secret
    devbox:secret:rm:
        click: insightscli_commands.devbox.cli:devbox_secret_rm
        description: Delete a Coder user secret
    devbox:config:show:
        click: insightscli_commands.devbox.cli:devbox_config_show
        description: Show saved devbox setup configuration
    devbox:config:rm:
        click: insightscli_commands.devbox.cli:devbox_config_rm
        description: Clear saved devbox configuration items
devenv:
    dev:setup:
        click: insightscli_commands.devenv.cli:dev_setup
        description: Interactive wizard to configure your dev environment
    dev:generate:
        click: insightscli_commands.devenv.cli:dev_generate
        description: Regenerate mprocs config from saved settings
    dev:explain:
        click: insightscli_commands.devenv.cli:dev_explain
        description: Show what services would be started for intents
    dev:intents:
        click: insightscli_commands.devenv.cli:dev_intents
        description: List available intents
    dev:regenerate-mprocs:
        click: insightscli_commands.devenv.cli:dev_regenerate_mprocs
        description: Sync bin/mprocs.yaml and bin/mprocs-e2e.yaml's docker-compose shells with generator.py
    dev:list-units:
        click: insightscli_commands.devenv.cli:dev_list_units
        description: List autostart units for given intents (used by phrocs)
        hidden: true
    dev:apply:
        click: insightscli_commands.devenv.cli:dev_apply
        description: Apply intent config non-interactively (used by phrocs)
        hidden: true
core:
    quickstart:
        click: insightscli_commands.quickstart:quickstart
        description: Show getting started with Insights development
    categories:
        description: Show all available commands grouped by category
    dev:up:
        description: Start full Insights dev stack via mprocs
        hidden: true
    dev:demo-data:
        cmd: python manage.py generate_demo_data
        description: Generate demo data for local testing
        services:
            - postgresql
            - datastore
    dev:bootstrap-project:
        cmd: python manage.py bootstrap_local_project
        description: Bootstrap a local project from an S3 events/persons dump (batch-export format)
        services:
            - postgresql
            - datastore
            - django
    dev:sync-flags:
        cmd: python manage.py sync_feature_flags
        description: Sync feature flags from configuration
        services:
            - postgresql
    dev:sync-script-templates:
        cmd: python manage.py sync_insights_function_templates
        description: Sync script function templates from configuration
        services:
            - postgresql
    dev:sync-user-settings:
        cmd: python manage.py sync_user_settings
        description: Sync your user settings from Insights cloud to local dev environment.
            Requires API key.
        services:
            - postgresql
    dev:shell-plus:
        cmd: python manage.py shell_plus
        description: Launch Django shell with auto-imported models and utilities
        services:
            - postgresql
            - datastore
            - django
    dev:reset:
        steps:
            - docker:services:remove
            - docker:services:up
            - setup:python
            - services:ready
            - insightscli: db:restore-schema
              prompt: Restore pre-migrated schema from CI? (faster than migrations)
              else: migrations:run
            # Skip demo-data's own network flag sync (us.hanzo.ai) — the
            # dev:sync-flags step below enables all flags from constants.tsx locally.
            - name: dev:demo-data
              cmd: python manage.py generate_demo_data --skip-flag-sync
            - dev:sync-flags
            - ensure:local:setup
        description: Full reset - wipe volumes, migrate, load demo data, sync flags
        prompt: true
    dev:api-key:
        cmd: python manage.py setup_local_api_key
        description: Creates a personal API key that's always the same, so you don't need
            to manually create a new one every time you reset the stack.
        services:
            - postgresql
health_checks:
    check:dagster-graphql:
        bin_script: check_dagster_graphql_up
        description: Wait for Dagster UI to become available
        hidden: true
    check:hosts:
        bin_script: check_hosts
        description: Verify DNS resolution for required service hostnames (datastore,
            kafka, etc)
        hidden: true
    check:video-deps:
        bin_script: check_video_deps
        description: Install and verify Playwright browsers and FFmpeg dependencies
        hidden: true
    services:ready:
        bin_script: wait-for-docker
        description: Wait for all Docker Compose services to pass health checks
start:
    start:
        bin_script: start
        description: Launch all dev services via phrocs (interactive TUI, or `-d` for detached mode)
        needs_secrets: true
        services:
            - phrocs
            - mprocs
            - docker
            - django
            - frontend
            - celery
            - nodejs
            - ingestion
            - postgresql
            - redis
            - kafka
            - datastore
            - temporal
    up:
        extends: start
        description: Alias for `insightscli start`; use `-d` for optional detached mode
    wait:
        cmd: phrocs wait
        description: Block until the detached dev stack is ready
        preserve_exit_code: true
    stop:
        cmd: phrocs stop
        description: Stop the detached dev stack processes (docker services stay up; use docker:services:down to stop them)
        preserve_exit_code: true
    down:
        cmd: phrocs stop
        description: Alias for `insightscli stop` (docker services stay up; use docker:services:down to stop them)
        preserve_exit_code: true
    start:backend:
        bin_script: start-backend
        description: Run Django development server on port 8000 with auto-reload
        # Django runtime — Max / AI features / Stripe billing all read keys
        # from .env.local at request time.
        needs_secrets: true
        services:
            - django
            - postgresql
            - redis
        hidden: true
    start:agent-proxy:
        cmd: pnpm --filter @hanzo/agent-proxy dev
        description: Run the agent-proxy Node service for task-run live streaming with auto-reload
        services:
            - redis
        hidden: true
    start:celery:
        bin_script: start-celery
        description: Start Celery worker or beat scheduler with auto-reload
        # Celery jobs hit AI providers (session summaries, batch exports, ...).
        needs_secrets: true
        services:
            - celery
            - redis
            - kafka
        hidden: true
    start:frontend:
        bin_script: start-frontend
        description: Install dependencies and start frontend with Vite dev server
        services:
            - frontend
            - docker
        hidden: true
    start:frontend-vite:
        bin_script: start-frontend-vite
        description: Start Vite dev server for frontend (runs pnpm start-vite)
        hidden: true
    start:worker:
        bin_script: start-worker
        description: Launch all background workers (Celery worker, beat scheduler, nodejs, ingestion)
        # Workers run AI / billing / ingestion code paths that touch external
        # providers — they need the runtime keys resolved.
        needs_secrets: true
        services:
            - celery
            - nodejs
            - ingestion
            - kafka
            - temporal
            - redis
        hidden: true
    start:rust-service:
        bin_script: start-rust-service
        description: Build and run live Rust microservice with auto-restart on crash
        # Rust services include batch-import-worker etc. that talk to Stripe
        # and other external endpoints.
        needs_secrets: true
        hidden: true
    start:go:service:
        bin_script: start-go-service
        description: Build and run Go microservices with auto-restart on crash
        needs_secrets: true
        hidden: true
deploy:
    deploy:hobby:
        bin_script: deploy-hobby
        description: Interactive installer for single-instance Insights deployment on remote
            server
    deploy:upgrade-hobby:
        bin_script: upgrade-hobby
        description: Upgrade existing hobby deployment with data loss warnings and volume
            checks
        prompt: true
    deploy:migrate-recordings:
        bin_script: migrate-session-recordings-hobby
        description: Migrate session recordings from MinIO to SeaweedFS for hobby deployments
    deploy:migrate-storage:
        bin_script: migrate-minio-to-seaweedfs
        description: "Migrate or sync object storage between MinIO and SeaweedFS\n\nServices:\
            \ session-recordings, session-recordings-lts, query-cache, \n         media-uploads,\
            \ exports, source-maps\n\nModes:\n  --mode migrate  One-way copy (default)\n\
            \  --mode sync     Bidirectional sync\n\nExamples:\n  insightscli deploy:migrate-storage\
            \ --service query-cache --mode sync --dry-run\n  insightscli deploy:migrate-storage\
            \ --service media-uploads --mode migrate"
        prompt: true
    deploy:migrate-storage-hobby:
        bin_script: migrate-storage-hobby
        description: "Hobby: Migrate or sync ALL services between MinIO and SeaweedFS\
            \ via docker-compose\n\nExamples:\n  insightscli deploy:migrate-storage-hobby    \
            \           # Sync all services\n  insightscli deploy:migrate-storage-hobby --mode\
            \ migrate # One-way migrate all (MinIO \u2192 SeaweedFS)\n  insightscli deploy:migrate-storage-hobby\
            \ exports -n     # Dry run exports only"
        prompt: true
    deploy:upgrade-objectstorage:
        bin_script: upgrade-objectstorage
        description: "Dev: salvage objectstorage data from the old MinIO volume into the\
            \ running SeaweedFS (interactive)\n\nExamples:\n  insightscli deploy:upgrade-objectstorage\
            \              # Detect and copy the orphaned MinIO volume\n  insightscli deploy:upgrade-objectstorage\
            \ --list       # List all MinIO volumes"
        services:
            - docker
        prompt: true
build:
    build:
        click: insightscli_commands.build:build
        description: Run code generation pipelines (smart change detection by default)
    build:frontend:
        cmd: pnpm --filter=@hanzo/frontend build
        description: Build frontend packages and run TypeScript compilation
        services:
            - frontend
    build:schema-json:
        cmd: pnpm --filter=@hanzo/frontend run schema:build:json
        description: Generate schema.json from frontend
    build:schema-python:
        bin_script: build-schema-python.sh
        description: Generate Pydantic schema.py from schema.json with datamodel-codegen
    build:schema-latest-versions:
        bin_script: build-schema-latest-versions.py
        description: Extract latest schema versions and generate frontend JSON config
    build:taxonomy-json:
        bin_script: build-taxonomy-json.py
        description: Generate core filter definitions taxonomy JSON for frontend
    build:bot-definitions:
        cmd: python livestream/bot/generate_definitions.py
        description: Generate livestream bot definitions JSON from bot_definitions.py
    build:schema:
        steps:
            - build:schema-json
            - build:schema-python
            - build:schema-latest-versions
        description: Generate all schema definitions (frontend JSON, Python, latest versions)
    build:openapi-schema:
        cmd: 'mkdir -p frontend/tmp && DEBUG=1 OPENAPI_INCLUDE_INTERNAL=1 OPENAPI_MOCK_INTERNAL_API_SECRET=1
            python manage.py spectacular --file frontend/tmp/openapi.json --format openapi-json --fail-on-warn
            && echo "OpenAPI schema written to frontend/tmp/openapi.json"

            '
        description: Generate OpenAPI schema from Django backend (writes to gitignored
            temp location)
        services:
            - postgresql
            - datastore
            - django
    build:schema-mcp:
        cmd: cd services/mcp && npx tsx scripts/generate-tool-schema.ts && pnpm exec oxfmt
            schema/tool-inputs.json
        description: Generate MCP tool-inputs.json schema from Zod definitions
    build:widget-types:
        steps:
            - cmd: python bin/build-dashboard-widget-types.py
            - cmd: pnpm --filter=@hanzo/frontend exec node
                  ../products/dashboards/frontend/bin/generate-widget-config-zod.mjs
        description: Generate dashboard widget config codegen artifacts (enum preflight, Zod)
    build:openapi-types:
        cmd: pnpm --filter=@hanzo/frontend run openapi:types
        description: Generate TypeScript API types from the backend OpenAPI schema
    build:openapi-mcp-types:
        cmd: pnpm --filter=@hanzo/mcp run generate-mcp-types
        description: Generate full TypeScript type namespace for MCP from OpenAPI schema
    build:openapi-mcp:
        cmd: pnpm --filter=@hanzo/mcp run generate-orval-schemas
        description: Generate Orval Zod schemas for MCP tool handlers
    build:openapi-mcp-tools:
        cmd: pnpm --filter=@hanzo/mcp run generate-tools
        description: Generate MCP tool handlers from YAML definitions + Orval schemas
    build:openapi-mcp-scopes:
        bin_script: build-mcp-oauth-scopes.py
        description: Generate OAUTH_SCOPES_SUPPORTED for the MCP protected-resource
            metadata from insights/scopes.py
    build:openapi-cli-agent-scopes:
        cmd: pnpm --filter=@hanzo/mcp run generate-cli-agent-scopes
        description: Generate the CLI `agent` login use-case scope list from the MCP
            tool definitions (must run after build:openapi-mcp-tools)
    build:openapi-exec-docs:
        cmd: pnpm --filter=@hanzo/mcp run generate-exec-docs
        description: Render the MCP exec tool's command reference into the markdown
            fragment hanzo.ai embeds in the tools reference page
    build:openapi:
        steps:
            - build:openapi-schema
            - build:widget-types
            - build:openapi-types
            - build:openapi-mcp-types
            - build:openapi-mcp
            - build:openapi-mcp-tools
            - build:openapi-mcp-scopes
            - build:openapi-cli-agent-scopes
            - build:openapi-exec-docs
        description: Generate OpenAPI schema and TypeScript types from the backend
    build:grammar:
        cmd: pnpm grammar:build
        description: Generate InsightsQL grammar definitions (C++)
    build:products:
        cmd: pnpm --filter=@hanzo/frontend run build:products
        description: Build products manifest from TypeScript/JSX files
    build:skills:
        cmd: python products/insights_ai/scripts/build_skills.py
        description: Build agent skills from products/*/skills/ into dist/skills/ and
            dist/skills.zip
    init:skill:
        cmd: python products/insights_ai/scripts/build_skills.py --init
        description: Scaffold a new agent skill directory with SKILL.md boilerplate
    sync:skill:
        cmd: python products/insights_ai/scripts/build_skills.py --sync
        description: Build a product skill and sync to .agents/skills/ for local testing
    unsync:skill:
        cmd: python products/insights_ai/scripts/build_skills.py --sync --clean
        description: Remove a previously synced skill from .agents/skills/
docker:
    docker:services:up:
        click: insightscli_commands.devenv.cli:docker_services_up
        description: Start Docker services based on your intent config
    docker:services:down:
        cmd: docker compose -f docker-compose.dev.yml --profile "*" down --remove-orphans
        description: Stop Docker infrastructure services
        services:
            - docker
    docker:services:remove:
        cmd: docker compose -f docker-compose.dev.yml --profile "*" down -v --remove-orphans
        description: Stop Docker infrastructure services and remove all volumes (complete
            wipe)
        services:
            - docker
        prompt: true
    docker:deprecated:
        bin_script: docker
        description: '[DEPRECATED] Use `insightscli start` instead'
        hidden: true
    docker:dev:
        bin_script: docker-dev
        description: '[DEPRECATED] Use `insightscli start` instead'
        hidden: true
    docker:dev-web:
        bin_script: docker-dev-web
        description: '[DEPRECATED] Use `insightscli start` instead'
        hidden: true
    docker:backend:
        bin_script: docker-backend
        description: '[DEPRECATED] Use `insightscli start:backend` instead'
        hidden: true
    docker:frontend:
        bin_script: docker-frontend
        description: '[DEPRECATED] Use `insightscli start:frontend` instead'
        hidden: true
    docker:migrate:
        bin_script: docker-migrate
        description: '[DEPRECATED] Use `insightscli migrations:run` instead'
        hidden: true
    docker:worker:
        bin_script: docker-worker
        description: '[DEPRECATED] Use `insightscli start:worker` instead'
        hidden: true
    docker:server:
        bin_script: docker-server
        description: Run dual-mode server (Granian/Unit) with Prometheus metrics support
        hidden: true
    docker:server-unit:
        bin_script: docker-server-unit
        description: Run NGINX Unit application server with configurable workers
        hidden: true
    docker:worker-beat:
        bin_script: docker-worker-beat
        description: Run Celery beat scheduler with RedBeat backend
        hidden: true
    docker:worker-celery:
        bin_script: docker-worker-celery
        description: Start Celery worker with optional scheduler, gossip, heartbeat, mingle
        hidden: true
    docker:ai-evals:
        bin_script: docker-ai-evals
        description: Set up Docker services and run evaluation scripts with cleanup
        hidden: true
migrations:
    db:migrate:
        bin_script: migrate
        description: Apply database migrations (Django and Datastore)
        hidden: true
    migrations:run:
        bin_script: migrate
        description: Run all database migrations (Datastore, Postgres, async) in parallel
        env:
            DEBUG: '1'
    migrations:datastore:
        cmd: bin/migrate --scope=datastore
        description: Initialize Datastore - run all Datastore migrations (and sync replicated schema)
        env:
            DEBUG: '1'
        services:
            - datastore
    migrations:check:
        bin_script: migrate-check
        description: Verify all migrations are ready without applying them
        services:
            - postgresql
            - datastore
    migrations:status:
        click: insightscli_commands.migrations:migrations_status
        description: Show migration diff between database and code
    migrations:down:
        click: insightscli_commands.migrations:migrations_down
        description: Roll back orphaned migrations
    migrations:up:
        click: insightscli_commands.migrations:migrations_up
        description: Apply pending migrations
    migrations:sync:
        click: insightscli_commands.migrations:migrations_sync
        description: 'Sync migrations: roll back orphaned, apply pending'
    migrations:cache-sync:
        click: insightscli_commands.migrations:migrations_cache_sync
        description: Populate cache from currently applied migrations
db:
    db:pg:
        cmd: psql postgres://insights:insights@localhost:5432/insights
        description: Connect to local PostgreSQL (extra args passed to psql)
        services:
            - postgresql
    db:ch:
        cmd: datastore client --host localhost --port 9000 --user default
        description: Connect to local Datastore (extra args passed to datastore client)
        services:
            - datastore
    db:dg:
        cmd: psql postgres://insights:insights@localhost:15432/ducklake
        description: Connect to local Duckgres (extra args passed to psql)
    db:upgrade:
        bin_script: upgrade-postgres
        description: Upgrade PostgreSQL from version 12 to 15 (interactive migration tool)
        services:
            - postgresql
            - docker
    db:dump:
        cmd: "mkdir -p .postgres-backups\nBACKUP_FILE=\"${1:-.postgres-backups/insights_backup_$(date\
            \ +%Y%m%d_%H%M%S).sql.gz}\"\ndocker compose exec -T db pg_dumpall --clean -U\
            \ insights | gzip > \"$BACKUP_FILE\"\necho \"\u2705 Backup saved to: $BACKUP_FILE\"\
            \n"
        description: Dump all PostgreSQL databases to compressed backup file
        services:
            - postgresql
            - docker
    db:restore:
        cmd: "set -e\nset -o pipefail\nif [ -z \"$1\" ]; then\n    LATEST=$(ls -t .postgres-backups/*.sql.gz\
            \ 2>/dev/null | head -1)\n    if [ -z \"$LATEST\" ]; then\n        echo \"\u274C\
            \ Error: No backup file specified and no backups found in .postgres-backups/\"\
            \n        echo \"Usage: insightscli db:restore [backup-file]\"\n        exit 1\n \
            \   fi\n    echo \"Using latest backup: $LATEST\"\n    BACKUP_FILE=\"$LATEST\"\
            \nelse\n    BACKUP_FILE=\"$1\"\nfi\nif [ ! -f \"$BACKUP_FILE\" ]; then\n   \
            \ echo \"\u274C Error: Backup file not found: $BACKUP_FILE\"\n    exit 1\nfi\n\
            gunzip -c \"$BACKUP_FILE\" | docker compose exec -T db psql -q -U insights >\
            \ /dev/null 2>&1\necho \"\U0001F510 Upgrading password to SCRAM-SHA-256...\"\
            \ndocker compose exec -T db psql -U insights -c \"ALTER USER insights WITH PASSWORD\
            \ 'insights';\" > /dev/null 2>&1\necho \"\u2705 Restored from: $BACKUP_FILE\"\
            \n"
        description: Restore PostgreSQL databases from backup file (defaults to latest)
        services:
            - postgresql
            - docker
    db:prime-test-db:
        steps:
            - db:download-schema
            - db:restore-test-db
        description: Download pre-migrated schema and prime the test_insights database for
            pytest --reuse-db
        services:
            - postgresql
            - docker
    db:restore-test-db:
        click: insightscli_commands.db_schema:db_restore_test_db
        description: 'Restore a fresh DB from a local schema dump (no download). Drops and
            recreates the target DB then loads schema-latest.sql.gz into it. Target DB
            defaults to test_insights; override via TARGET_DB env var. Used by CI after
            restoring the schema from Actions cache.'
        services:
            - postgresql
            - docker
    db:restore-schema-fresh:
        click: insightscli_commands.db_schema:db_restore_schema_fresh
        description: Alias for db:restore-test-db. Kept so PR branches that pulled in the
            short-lived rename (#57657) still resolve a valid command after the revert.
            Safe to remove once those branches are merged or rebased.
    db:download-schema:
        click: insightscli_commands.db_schema:db_download_schema
        description: Download the newest compatible pre-migrated schema artifact from CI
            (requires gh auth or GH_TOKEN)
    db:restore-schema-if-fresh:
        click: insightscli_commands.db_schema:db_restore_schema_if_fresh
        description: Restore a compatible schema into an empty local dev database before
            migrations. Defaults to best-effort auto mode; set INSIGHTS_SCHEMA_RESTORE_IN_DEV=off
            to disable or on to fail on restore errors.
        services:
            - postgresql
            - docker
    db:restore-schema:
        click: insightscli_commands.db_schema:db_restore_schema
        description: Fetch pre-migrated schema from CI, restore it, and run any pending
            migrations (creates backup first)
        services:
            - postgresql
            - docker
tests:
    test:
        click: insightscli_commands.test_runner:test_command
        description: Auto-detect test type (Python, Jest, Playwright, Rust, Go) and run it
    test:python:
        cmd: pytest
        description: Run Python test suite
    test:js:
        cmd: pnpm --filter=@hanzo/frontend test
        description: Run JavaScript test suite
    test:e2e:
        bin_script: e2e-test-runner
        description: Set up test databases and run Playwright E2E tests
    test:quarantine:
        click: insightscli_commands.quarantine.cli:quarantine
        description: Manage .test_quarantine.json — quarantine flaky tests so they stop blocking CI
    evals:
        cmd: python -m products.insights_ai.eval_harness.harness
        description: Run evals — sandboxed agent and one-shot suites (extra args pass through, e.g. `sql` or `cli_mcp --provider modal`)
        needs_secrets: true
    evals:sandboxed:
        cmd: python -m products.insights_ai.eval_harness.harness
        description: Alias of `evals` (kept for back-compat)
        needs_secrets: true
quality:
    lint:
        cmd: ./bin/ruff.sh check . && pnpm --filter=@hanzo/frontend run lint
        description: Run Python and JS/TS linting
    format:
        cmd: pnpm format
        description: Format both backend and frontend code
    format:yaml:
        cmd: pnpm exec oxfmt --no-error-on-unmatched-pattern "$@"
        description: Format JSON, YAML files
    format:css:
        cmd: pnpm stylelint --fix --allow-empty-input "$@" && pnpm exec oxfmt --no-error-on-unmatched-pattern
            "$@"
        description: Format CSS/SCSS files
    format:js:
        cmd: pnpm oxlint --fix --fix-suggestions --quiet --no-error-on-unmatched-pattern
            "$@" && pnpm exec oxfmt --no-error-on-unmatched-pattern "$@"
        description: Format JavaScript/TypeScript files (frontend)
    format:nodejs:
        cmd: pnpm --dir nodejs exec eslint --fix "$@" && pnpm --dir nodejs exec prettier
            --write "$@"
        description: Format nodejs JavaScript files
    format:rust:
        cmd: rustfmt
        description: Format Rust files
    format:python:
        cmd: ./bin/ruff.sh format
        description: Format Python files
    lint:skills:
        cmd: python products/insights_ai/scripts/build_skills.py --lint
        description: Validate agent skill sources (syntax, frontmatter, depth constraints)
    lint:python:fix:
        cmd: ./bin/ruff.sh check --fix
        description: Fix Python code quality issues
    format:markdown:
        cmd: pnpm exec markdownlint-cli2 --config .config/.markdownlint-cli2.jsonc --fix
            "$@" && pnpm exec oxfmt --no-error-on-unmatched-pattern "$@"
        description: Format Markdown files
    lint:feature-flags:
        cmd: node bin/lint-feature-flag-sorting.mjs
        description: Check that FEATURE_FLAGS in constants.tsx are alphabetically sorted
    lint:feature-flags:fix:
        cmd: node bin/lint-feature-flag-sorting.mjs --fix
        description: Auto-sort FEATURE_FLAGS in constants.tsx alphabetically
    lint:workflows:
        click: insightscli_commands.workflow_lint.cli:cmd_lint_workflows
        description: Lint .github/workflows/** for repo conventions
    lint:migration-deletions:
        click: insightscli_commands.migration_deletions:cmd_lint_migration_deletions
        description: Block deleting historical Django migration files
    format:mcp:
        cmd: pnpm run --filter @hanzo/mcp format
        description: Format MCP files
auth:
    metabase:login:
        click: insightscli_commands.metabase:metabase_login
        description: Log in to Metabase via SSO and cache the session cookie
    metabase:cookie:
        click: insightscli_commands.metabase:metabase_cookie
        description: Print the cached Metabase cookie header
tools:
    metabase:databases:
        click: insightscli_commands.metabase:metabase_databases
        description: List Metabase databases (id, name, engine) for a region
    metabase:query:
        click: insightscli_commands.metabase:metabase_query
        description: Run a SQL query against Metabase /api/dataset; results to stdout
    doctor:
        click: insightscli_commands.doctor:doctor
        description: Quick health check for your dev environment
    doctor:disk:
        click: insightscli_commands.doctor:doctor_disk
        description: Interactive disk space cleanup for common Insights dev bloat
    doctor:zombies:
        click: insightscli_commands.doctor:doctor_zombies
        description: Find and kill orphaned Insights dev processes
    doctor:ports:
        click: insightscli_commands.doctor:doctor_ports
        description: Pre-flight check for host ports the dev stack needs
    doctor:migrate-volumes:
        click: insightscli_commands.doctor:doctor_migrate_volumes
        description: Auto-migrate Datastore/ZooKeeper data to the new named docker volumes
    doctor:report:
        click: insightscli_commands.doctor:doctor_report
        description: Dump a paste-ready dev-environment diagnostics report for devex triage
    product:bootstrap:
        click: insightscli_commands.product.cli:cmd_bootstrap
        description: Scaffold a new product with canonical structure
    product:lint:
        click: insightscli_commands.product.cli:cmd_lint
        description: Check product structure for misplaced files
    product:isolate:scan:
        click: insightscli_commands.product.cli:cmd_isolate_scan
        description: Read-only isolation recon for the facade migration skill
    product:isolate:move:
        click: insightscli_commands.product.cli:cmd_isolate_move
        description: Mechanical isolation moves with repo-wide path rewrites
    product:lint:owners:
        click: insightscli_commands.product.cli:cmd_lint_owners
        description: Validate product.yaml owners against Insights/insights GitHub teams
    product:maturity:
        click: insightscli_commands.product.cli:cmd_maturity
        description: Score product maturity across isolation dimensions
    tool:temporal-codec-server:
        bin_script: temporal-codec-server
        description: Run a local Temporal codec server to decode Fernet payloads for debugging
        hidden: true
    tool:temporal-django-worker:
        bin_script: temporal-django-worker
        description: Start Temporal worker with graceful shutdown handling
    tool:temporal-recording-rasterizer-worker:
        bin_script: temporal-recording-rasterizer-worker
        description: Start recording rasterizer Temporal worker (Puppeteer + Chromium)
        hidden: true
    tool:download-mmdb:
        bin_script: download-mmdb
        description: Download and cache GeoLite2 MaxMind database with retry logic
    tool:download-sentiment-model:
        bin_script: download-sentiment-model
        description: Download and export sentiment ONNX model for local AI observability
            development
        services:
            - temporal
    tool:script:
        bin_script: script
        description: Run a .script program or compiled .scriptc bytecode on the script
            VM (nodejs by default, --python for the Python VM)
    tool:scriptc:
        bin_script: scriptc
        description: Compile a .script program to .scriptc bytecode or JavaScript
    tool:ruff:
        bin_script: ruff.sh
        description: Python linter and formatter with virtualenv auto-activation
    tool:turbo:
        bin_script: turbo
        description: Turborepo wrapper with automatic dependency installation
    tool:unit-metrics:
        bin_script: unit_metrics.py
        description: WSGI app that aggregates Prometheus metrics from NGINX Unit status
            endpoint
        hidden: true
    tool:create-ch-migration:
        cmd: python manage.py create_ch_migration
        description: Generate new Datastore migration scaffold
    tool:print-script-stl:
        cmd: python manage.py print_script_stl_table
        description: Print the script standard library definitions for reference
        hidden: true
    datastore:logs:init:
        bin_script: datastore-logs-init
        description: Initialize Datastore logs schema (temporary, pre-migration)
        hidden: true
    datastore:metrics:init:
        bin_script: datastore-metrics-init
        description: Initialize Datastore metrics schema (temporary, pre-migration)
        hidden: true
    datastore:multinode:start:
        cmd: tools/infra-scripts/datastore-multinode/start-multinode-datastore
        description: Boot the multinode Datastore smoke-test stack (one server per logical cluster) for local migration verification
        hidden: true
    datastore:multinode:verify:
        cmd: python tools/infra-scripts/datastore-multinode/verify-multinode-datastore.py
        description: Assert that the multinode Datastore stack ended up with the expected per-node table layout
        hidden: true
    datastore:multinode:test:
        cmd: tools/infra-scripts/datastore-multinode/multinode-migration-smoke
        description: Boot a per-cluster Datastore stack and smoke-test migrations against it
        hidden: true
    create:notebook:node:
        bin_script: create-notebook-node.sh
        description: Create a new NotebookNode file and update types and editor references
        hidden: true
    tool:granian-metrics:
        bin_script: granian_metrics.py
        description: HTTP server that aggregates Prometheus metrics from Granian workers
        hidden: true
    sync:storage:
        bin_script: sync-storage
        description: 'Sync object storage between MinIO and SeaweedFS, per service or all of them'
        hidden: true
    tool:check_ducklake_up:
        bin_script: check_ducklake_up
        description: Healthcheck for Ducklake with self-healing
        hidden: true
    start:llm:gateway:
        bin_script: start-llm-gateway
        description: Start the LLM gateway service
        needs_secrets: true
        hidden: true
    insights:node:
        bin_script: insights-node
        description: Start the insights-node service (old plugin-server)
        needs_secrets: true
        hidden: true
    start:mcp:server:
        bin_script: start-mcp-server
        description: Start the MCP server
        needs_secrets: true
        hidden: true
    start:stripe:app:
        bin_script: start-stripe-app
        description: Start the Stripe app dev server (requires Stripe CLI)
        needs_secrets: true
    generate_personinsights_proto:
        bin_script: generate_personinsights_proto.sh
        description: 'Regenerate the personinsights protobuf clients from proto/ into the generated package'
        hidden: true
    phrocs:build:
        cmd: cd tools/phrocs && make build
        description: Build the phrocs binary from source
    ci:wait:for:docker:
        bin_script: ci-wait-for-docker
        description: Launch Docker Compose services in CI and later wait for readiness
        hidden: true
    ci:find_affected_stories:
        bin_script: find-affected-stories
        description: Compute the set of stories affected by changed files during storybook builds
        hidden: true
    ci:frontend_exclude_filter:
        bin_script: frontend-exclude-filter
        description: Emit the dorny paths-filter excluding Node-only product workspaces (from pnpm-workspace.yaml) for frontend/storybook CI gating
        hidden: true
    ci:insights:
        click: insightscli_commands.ci_insights:ci_insights
        description: Show CI insights for the current repo + branch (search/view/plan subcommands)
    ci:preflight:
        click: insightscli_commands.ci_preflight:ci_preflight
        description: Catch deterministic CI failures reachable from your diff before you push (advisory; --fix, --strict)
    publish:static:
        bin_script: publish-static
        description: 'Mirror a built STATIC_ROOT into the shared object origin, so chunks outlive the pod that built them'
        hidden: true
    prune:static:
        bin_script: prune-static
        description: 'Hold the static origin to its 30-day deploy horizon'
        hidden: true
desktop:
    desktop:dev:
        cmd: pnpm --dir products/desktop dev
        description: Run the desktop app dev stack (build deps, then phrocs with Electron)
    desktop:test:
        cmd: pnpm --dir products/desktop test
        description: Run desktop unit tests (Vitest via turbo, nested workspace)
    desktop:typecheck:
        cmd: pnpm --dir products/desktop typecheck
        description: Typecheck all desktop packages (turbo)
    desktop:lint:
        cmd: pnpm --dir products/desktop exec biome ci . && node products/desktop/scripts/check-host-boundaries.mjs
        description: Check desktop code quality without writing (Biome + host boundaries, mirrors desktop-quality CI)
    desktop:lint:fix:
        cmd: pnpm --dir products/desktop run lint
        description: Autofix desktop lint issues (biome check --write --unsafe)

owners:
    owners:resolve:
        click: insights_owners.cli:cmd_resolve
        description: Resolve ownership for paths (args or newline-delimited stdin); --json for machine output
    owners:who:
        click: insights_owners.cli:cmd_who
        description: Show who owns a single path (owners, status, slack, source)
    owners:unowned:
        click: insights_owners.cli:cmd_unowned
        description: List unowned tracked files, respecting owners:null exemptions (optional PREFIX)
    owners:lint:
        click: insights_owners.cli:cmd_lint
        description: Validate owners.yaml schema, product.yaml conflicts, dead globs, coverage (--live checks the GitHub org)
    owners:fmt:
        click: insights_owners.cli:cmd_fmt
        description: Dry-run oracle showing how the owners.yaml layout differs from canonical placement (never writes)
devex:
    devex:feedback:
        click: insightscli_commands.feedback:devex_feedback
        description: Send feedback about the dev experience to the devex team (humans and agents)
utilities:
    nuke:
        steps:
            - name: announce
              cmd: say -v 'Samantha' 'Nuclear launch detected' 2>/dev/null || true
            - name: node_modules
              cmd: rm -rf **/node_modules
            - name: python venvs
              cmd: rm -rf .venv .flox/cache/venv
            - name: rust builds
              cmd: cd rust && cargo clean && find . -name 'index.node' -type f -delete
            - name: flox on activate
              cmd: ./.flox/env/on-activate.sh
            - dev:reset
        description: Wipe everything and rebuild (node_modules, Python, Rust, then dev:reset)
        prompt: true
    worktrees:clean:
        click: insightscli_commands.worktrees:worktrees_clean
        description: Clear out unused Claude Code / Codex / Insights Desktop worktrees by age
    pr:upload-image:
        click: insightscli_commands.upload_image:upload_image
        description: Upload screenshot(s) to the public Insights/pr-assets repo and print embeddable PR markdown
    pr:upload-video:
        click: insightscli_commands.upload_video:upload_video
        description: Upload demo video(s) to the public Insights/pr-assets repo and print link markdown
    utilities:insights-worktree:
        bin_script: insights-worktree
        description: Manage isolated git worktrees for Insights development
        hidden: true
    utilities:phw:
        bin_script: phw
        description: Shell function wrapper for worktree management with auto-cd
        hidden: true
    utilities:update-bots-list:
        bin_script: update-bots-list
        description: Download bot IP list from GoodBots GitHub and save locally
        hidden: true
    utilities:dump-scriptvmrs-stl:
        bin_script: dump_scriptvmrs_stl
        description: Generate Rust ScriptVM standard library definitions for error tracking
        hidden: true
    utilities:hobby-ci:
        bin_script: hobby-ci.py
        description: DigitalOcean CI automation for Hobby deployment testing
        hidden: true
    utilities:install-insightscli-completion:
        bin_script: install-insightscli-completion
        description: Install shell completion for insightscli (bash/zsh)
        hidden: true
    utilities:check-uv-python-compat:
        bin_script: check_uv_python_compatibility.py
        description: CI validation for uv/Python version compatibility
        hidden: true
environment:
    flox:activate:
        cmd: flox activate
        description: Enter Flox development environment shell.
        hidden: true
    setup:python:
        cmd: uv sync --active
        description: Install Python dependencies to active virtual environment
    sandbox:
        bin_script: sandbox
        description: Manage isolated dev sandboxes
    start:stripe:mock:
        bin_script: start-stripe-mock
        description: 'Start the local Stripe mock API server'
        hidden: true
    fix:rdkafka:paths:
        bin_script: fix-rdkafka-paths
        description: 'Rewrite node-rdkafka dylib paths to use @loader_path on macOS for worktree portability'
        hidden: true
    warm:flags:cache:
        bin_script: warm-flags-cache
        description: 'Warm the feature-flags hypercache against the local dev environment (requires ./bin/start running)'
        hidden: true
    flags:jumphost:
        bin_script: rust-jumphost
        description: 'Shell into the flags-cache-jumphost pod (uses $KUBE_NAMESPACE, defaults to insights)'
        hidden: true
    wait:for:postgres:tables:
        bin_script: wait-for-postgres-tables
        description: 'Block until the named Postgres tables exist'
        hidden: true
    dev:sandbox:
        bin_script: dev-sandbox
        description: 'Run a command inside the dev filesystem sandbox (internal; used by insightscli dev:generate by default unless INSIGHTS_DEV_SANDBOX=0)'
        hidden: true
    dev:sandbox:selftest:
        bin_script: dev-sandbox-selftest
        description: 'Verify the dev sandbox profile: blocks credentials/escapes, allows the toolchain'
        hidden: true
    build:dashboard:widget:types:
        bin_script: build-dashboard-widget-types.py
        description: Widget enum preflight, date options, and form-field manifest codegen
        hidden: true
    start:ai:gateway:
        bin_script: start-ai-gateway
        description: 'Bring up the local Go ai-gateway via docker compose and top up the anonymous-team ledger for AGENT_USE_AI_GATEWAY dev'
        hidden: true
    dockerignore:drop:check:
        bin_script: dockerignore-drop-check
        description: List files an .dockerignore change drops from the image build context
        hidden: true
    verify:metrics:pipe:
        bin_script: verify-metrics-pipe
        description: 'Verify the local metrics pipe reached Datastore metrics1'
        hidden: true
    send:dev:metrics:
        bin_script: send-dev-metrics.sh
        description: 'Send a synthetic OTLP counter/gauge/histogram through the metrics ingest chain'
        hidden: true
    inject_mcp_intents:
        bin_script: inject_mcp_intents.py
        description: 'Used when developing MCP Analytics locally and trying to load some intents'
        hidden: true
    dev:sandbox:shims:selftest:
        bin_script: dev-sandbox-shims-selftest
        description: 'Verify the uv/pnpm dev-sandbox shims route install subcommands correctly'
        hidden: true
    setup:gateway:e2e:
        bin_script: setup-gateway-e2e
        description: 'Provision the local ai-gateway e2e: enable the team, mint a sk-, publish the credential blob, fund the ledger'
        hidden: true
    dev:open:when:ready:
        bin_script: dev-open-when-ready
        description: 'Open a URL in the browser once its server is listening (internal; runs unsandboxed so sandboxed procs can auto-open)'
        hidden: true
    docker:agent:proxy:
        cmd: node dist/agent-proxy-server.mjs
        description: 'Production entrypoint: run the agent-proxy Node service'
        hidden: true
    ensure:local:setup:
        bin_script: ensure-local-setup
        description: Idempotent local-dev bootstrap (e.g. the wizard OAuth app); runs automatically on insightscli start
        hidden: true
    start:desktop:
        bin_script: start-desktop
        description: 'Install the nested products/desktop workspace and run its dev stack (Electron app plus package watchers via turbo); used by the desktop intent on insightscli start'
        hidden: true
    check:forge:credential:
        bin_script: check-forge-credential
        description: 'Answer in seconds whether this build can read the forge, before a long build spends the hour finding out'
        hidden: true
    check:imports:are:committed:
        bin_script: check-imports-are-committed
        description: 'Check that every first-party import resolves to a committed file, so a fresh clone of this commit starts'
        hidden: true
    debrand:
        bin_script: debrand
        description: 'Rewrite an upstream tree into the Hanzo Insights tree; --check asserts the rename holds'
        hidden: true
    debrand:selftest:
        bin_script: debrand-selftest
        description: 'Self-test bin/debrand, one check per rename defect that has happened before'
        hidden: true
    tables:
        bin_script: tables
        description: 'Report the warehouse table names this tree declares, and refuse a versioned one'
        hidden: true
    theme:
        bin_script: theme
        description: 'Assert the Hanzo design tokens survive a rebase onto upstream'
        hidden: true