# 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