npm package: @kite-copilot/cli
Description: Kite CLI - Analyze frontend codebases and map API calls
Author: Kite
Latest version: 1.0.2

# @kite/cli

Command-line tool for analyzing frontend codebases to discover API mappings. The CLI uses Claude AI to analyze your frontend code, identify routes, API calls, and generate mappings that connect your frontend to the Kite backend.

## Prerequisites

### Claude CLI

The Kite CLI requires Claude CLI to be installed for code analysis:

```bash
npm install -g @anthropic-ai/claude-cli
```

Verify installation:

```bash
claude --version
```

### Node.js

Requires Node.js 18.0.0 or higher.

## Installation

### From npm (when published)

```bash
npm install -g @kite/cli
```

### From source

```bash
cd agent/cli-npm
npm install
npm run build
```

Then run with:

```bash
node dist/index.js <command>
```

Or create a global link:

```bash
npm link
kite <command>
```

## Commands

### `kite login`

Authenticate with the Kite backend.

```bash
kite login [--backend-url <url>]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--backend-url <url>` | Kite backend URL (default: https://api.kite.com) |

**Environment Variables:**

| Variable | Description |
|----------|-------------|
| `KITE_BACKEND_URL` | Override default backend URL |

**Example:**

```bash
# Login to production
kite login

# Login to local development server
kite login --backend-url http://localhost:5002
```

When prompted, enter your API token from the Kite dashboard.

### `kite logout`

Clear stored credentials.

```bash
kite logout
```

### `kite status`

Show current login status.

```bash
kite status
```

### `kite map`

Analyze a frontend codebase to discover API mappings.

```bash
kite map <path> [options]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `<path>` | Path to the frontend codebase directory |

**Options:**

| Option | Description |
|--------|-------------|
| `-o, --output <file>` | Output JSON file path (default: kite-mappings.json) |
| `-u, --upload` | Upload mappings to Kite backend after analysis |
| `-q, --quiet` | Suppress terminal visualization output |
| `-v, --verbose` | Show verbose debug output |
| `--timeout <seconds>` | Analysis timeout in seconds (default: 300) |
| `--no-output-file` | Don't generate output JSON file |

**Examples:**

```bash
# Analyze and save to default file
kite map ./my-frontend-app

# Analyze with custom output file
kite map ./my-frontend-app -o custom-mappings.json

# Analyze and upload to backend
kite map ./my-frontend-app --upload

# Quiet mode - just generate the file
kite map ./my-frontend-app --quiet

# Verbose mode for debugging
kite map ./my-frontend-app --verbose

# Increase timeout for large codebases
kite map ./my-frontend-app --timeout 600
```

## Configuration

Credentials are stored in `~/.kite/config.json`:

```json
{
  "token": "your-api-token",
  "org_id": "organization-uuid",
  "api_config_id": "config-uuid",
  "email": "your@email.com",
  "org_name": "Your Organization",
  "backend_url": "https://api.kite.com"
}
```

## Output Format

The `kite map` command generates a JSON file with the following structure:

```json
{
  "version": "1.0",
  "generated_at": "2024-01-15T10:30:00Z",
  "codebase_path": "/path/to/frontend",
  "routes": [
    {
      "route_name": "customers",
      "file_path": "pages/customers.tsx",
      "component_name": "CustomersPage"
    }
  ],
  "api_calls": [
    {
      "endpoint": "/api/customers",
      "method": "GET",
      "component_file": "pages/customers.tsx",
      "action_form_type": null
    }
  ],
  "mappings": [
    {
      "tool_name": "customers",
      "api_endpoint": "/api/customers",
      "navigation_page": "customers",
      "action_form_type": "addCustomer",
      "frontend_component": "CustomersPage",
      "frontend_file_path": "pages/customers.tsx"
    }
  ]
}
```

## Workflow

### First-time Setup

1. Install the CLI and Claude CLI
2. Get your API token from the Kite dashboard
3. Login: `kite login`
4. Verify: `kite status`

### Analyzing a Codebase

1. Navigate to your project or provide the path
2. Run: `kite map ./your-frontend --upload`
3. Review the generated mappings
4. Mappings are now available in the Kite backend

### Local Development

For local development without Supabase:

```bash
# 1. Seed local test data
python agent/app/scripts/seed_local_dev.py

# 2. Start the backend
cd agent && python server.py

# 3. Login to local backend
kite login --backend-url http://localhost:5002

# 4. Map your codebase
kite map ./your-frontend --upload
```

## Troubleshooting

### Claude CLI not found

```
Error: Claude CLI not found
```

**Solution:** Install Claude CLI:

```bash
npm install -g @anthropic-ai/claude-cli
```

### Analysis timeout

```
Error: Analysis timed out after 300 seconds
```

**Solution:** Increase the timeout:

```bash
kite map ./large-codebase --timeout 600
```

### Authentication failed

```
Error: Invalid token
```

**Solution:** Re-run login:

```bash
kite logout
kite login
```

### Not logged in

```
Error: Not logged in. Run 'kite login' first.
```

**Solution:** Login before uploading:

```bash
kite login
kite map ./frontend --upload
```

### Path is not a frontend project

```
Error: Directory doesn't appear to be a frontend project
```

**Solution:** Ensure your path contains one of:
- `package.json`
- `tsconfig.json`
- `src/` directory
- `app/` directory
- `components/` directory
- `pages/` directory

## Development

### Building

```bash
npm run build
```

### Development mode

```bash
npm run dev
```

### Running from source

```bash
node dist/index.js map ./test-frontend
```

## License

MIT