@wip-group/falcon-cli

# Falcon CLI The official command-line interface for Falcon - track your development activity, manage environment variables, and run commands with automatic env injection. ## Installation ```bash bun install -g @wip-group/falcon-cli ``` ## Quick Start 1. **Authenticate with Falcon** ```bash falcon auth login ``` This opens a browser window for secure authentication. 2. **Initialize your project** ```bash falcon init ``` Creates a `falcon.json` file with your project configuration. 3. **Start developing** ```bash falcon dev ``` Runs your development server with environment variables automatically injected. ## Commands ### Authentication #### `falcon auth login` Authenticate with Falcon via browser-based OAuth flow. #### `falcon auth logout` Log out from Falcon and remove stored credentials. ### Development #### `falcon dev [command...]` Run your development server with automatic environment variable injection and activity tracking. ```bash # Run default dev command (bun run dev) falcon dev # Run custom dev command falcon dev npm start falcon dev yarn dev falcon dev -- python manage.py runserver ``` **Features:** - Automatically injects environment variables from Falcon - Tracks development activity (file changes, restarts) - Auto-restarts on crashes (for default dev command) - Shows which env vars are loaded (local vs remote) #### `falcon run <command...>` Run any command with environment variables injected (without activity tracking). ```bash # Run tests with env vars falcon run npm test # Run build with env vars falcon run bun run build # Run any script falcon run -- node scripts/migrate.js ``` ### Project Management #### `falcon project` Display detailed information about your current project. ```bash falcon project # Pretty formatted output falcon project --json # JSON output for automation ``` Shows: - Project name and description - Owner and team members - Linked GitHub repositories - Environment variable count - Recent activity - Direct link to web dashboard ### Environment Variables #### `falcon env` List all environment variables (default action). ```bash falcon env # or falcon env list ``` #### `falcon env get <key>` Get the value of a specific environment variable. ```bash falcon env get DATABASE_URL falcon env get API_KEY ``` #### `falcon env set <key> <value>` Set or update an environment variable. ```bash # Set a regular variable falcon env set NODE_ENV production # Set a secret (value will be masked in lists) falcon env set DATABASE_URL "postgres://..." --secret ``` #### `falcon env delete <key>` Delete an environment variable. ```bash # Interactive confirmation falcon env delete OLD_API_KEY # Skip confirmation falcon env delete OLD_API_KEY --force ``` #### `falcon env import <file>` Import environment variables from a file. ```bash # Import from .env file falcon env import .env # Import from any file falcon env import production.env ``` ### Project Configuration #### `falcon init` Initialize a new Falcon project configuration. Creates a `falcon.json` file in your project root: ```json { "project": "my-awesome-app" } ``` ## Environment Variable Priority When running commands with `falcon dev` or `falcon run`, environment variables are loaded in this order (later sources override earlier ones): 1. Your system environment variables 2. Local `.env` file (if present) 3. Local `falcon.json` env section (if present) 4. Remote environment variables from Falcon This ensures that: - Your existing setup continues to work - Remote variables can override local development values - You have full control over variable precedence ## Examples ### Starting a Next.js Project ```bash # Initialize falcon init falcon auth login # Set up environment falcon env set NEXT_PUBLIC_API_URL https://api.example.com falcon env set DATABASE_URL postgres://... --secret # Start developing falcon dev ``` ### Running Tests in CI/CD ```bash # In your CI/CD pipeline falcon auth login falcon run npm test falcon run npm run build ``` ### Managing Multiple Environments ```bash # Import production variables falcon env import .env.production # View all variables falcon env # Update a specific variable falcon env set API_URL https://api-v2.example.com ``` ### Automation with Claude or Scripts ```bash # Get project info as JSON PROJECT_ID=$(falcon project --json | jq -r '._id') # Set multiple variables falcon env set NODE_ENV production falcon env set LOG_LEVEL info falcon env set FEATURE_FLAG_X enabled # Run deployment falcon run npm run deploy ``` ## Migration from existing projects If you have an existing project with a `.env` file that you want to migrate to Falcon: 1. **Create the project in Falcon dashboard** - Go to https://falcon.wip.group - Create a new project with your desired name (e.g., "MyAwesomeProject") - **IMPORTANT**: Note the EXACT project name - it's case sensitive! 2. **Initialize Falcon in your local project** ```bash falcon init ``` - When prompted for project name, enter the EXACT SAME NAME (case sensitive!) - Example: If you created "MyAwesomeProject" in the dashboard, type exactly "MyAwesomeProject" 3. **Import your existing .env file** ```bash falcon env import .env ``` That's it! Your environment variables are now synced to Falcon and will be automatically injected when you run `falcon dev`. ## Tab Completion Enable tab completion for your shell: ```bash # Bash falcon completion bash >> ~/.bashrc source ~/.bashrc # Zsh falcon completion zsh >> ~/.zshrc source ~/.zshrc # Fish falcon completion fish > ~/.config/fish/completions/falcon.fish ``` ## Configuration - Auth credentials are stored in `~/.falcon/config.json` - Project configuration is stored in `falcon.json` in your project root ## Troubleshooting ### "Not authenticated" Error Run `falcon auth login` to authenticate. ### "No project configured" Error Run `falcon init` in your project directory. ### Environment Variables Not Loading 1. Check you're authenticated: `falcon auth login` 2. Verify project name in `falcon.json` 3. Ensure you have access to the project ## Development For local development of the CLI itself: ```bash # Clone the repository git clone https://github.com/wip-group/falcon.git cd falcon/packages/falcon-cli # Install dependencies bun install # Link for local testing bun link # Use development version falcon-dev <command> ``` ## Support - GitHub Issues: https://github.com/wip-group/falcon/issues - Documentation: https://falcon.wip.group/docs ## License MIT