Visão Geral

The Gaio CLI is a command-line interface tool designed to streamline the setup and management of development environments for Gaio projects. It provides commands to automate environment setup, generate LLM documentation, and validate configurations.

🚀 Quick Start

After cloning the repository and running npm install, the CLI is automatically available:

npm install         # Auto-setup CLI and development environment
gaio --help         # See available commands
gaio status         # Check current setup status

📋 Available Commands

gaio setup / gaio s

Setup the development environment and generate LLM documentation with intelligent validation.

gaio setup              # Smart setup (skips if already configured)
gaio setup --force      # Force complete re-setup
gaio setup --status     # Show setup status only

gaio llm / gaio l

Generate LLM documentation from the docs/ directory.

gaio llm

gaio status

Show CLI setup status and configuration information.

gaio status

gaio help / gaio h

Show enhanced help information with examples.

gaio help

⚙️ Configuration

The CLI automatically detects the project structure:

• Source: docs/ for LLM documentation
• Entry Points: AGENTS.md and CLAUDE.md symbolic links
• State: .gaio.json for setup validation (includes hash for docs change detection)

🛠️ Development

Building

npm run build -w @gaio/cli     # Build CLI from TypeScript
npm run build:watch -w @gaio/cli # Watch mode for development

Development Mode

npm run dev -w @gaio/cli       # Run CLI in development with tsx
npm run dev:watch -w @gaio/cli # Development with hot reload

Testing

npm run test -w @gaio/cli      # Run CLI tests
npm run test:commands -w @gaio/cli # Test all CLI commands

Type Checking

npm run typecheck -w @gaio/cli # TypeScript type checking

🔧 How It Works

1. Installation: npm install triggers postinstall script
2. Setup Detection: Checks for existing setup state and files
3. Project Root Finding: Intelligently locates monorepo root
4. LLM Generation: Processes documentation files and creates entry points
5. State Saving: Records successful setup for future validation

🎯 Best Practices

For Development

• Use npm run dev -w @gaio/cli for development work
• Run gaio setup after pulling major changes
• Use gaio status to debug setup issues
• Use --force flag only when necessary changes are made
• Check docs/ directory structure if LLM generation fails

For CI/CD

• Use gaio setup --force in CI environments for consistency
• Validate setup with gaio status before running commands
• Cache .llm/ directory to speed up builds when possible

🚨 Troubleshooting

CLI Not Found

npm install --workspace=@gaio/cli    # Reinstall CLI workspace
npm run build -w @gaio/cli           # Rebuild from source

Permission Denied

chmod +x tools/cli/bin/cli.js   # Fix executable permissions
npm run build -w @gaio/cli              # Rebuild with proper permissions

Setup Not Working

gaio status                             # Check setup status
gaio setup --force                      # Force complete re-setup
rm .gaio.json && gaio setup           # Reset and re-setup

Project Root Not Found

# Ensure you're in a valid Gaio project directory
ls package.json docs/                  # Verify required files exist
gaio setup --force                     # Force re-detection