npm package: @proposeflow/cli
Description: CLI for ProposeFlow - manage schemas and sync with the API
Author: Quinton Miller
Latest version: 0.1.2

# @proposeflow/cli

Command-line interface for managing ProposeFlow schemas.

## Installation

```bash
npm install -g @proposeflow/cli
# or use via pnpm in the monorepo
pnpm --filter @proposeflow/cli build
```

## Quick Start

```bash
# Initialize ProposeFlow in your project
proposeflow init

# Push local schemas to the API
proposeflow push

# Pull schemas and generate TypeScript types
proposeflow pull --output ./src/schemas

# Launch interactive TUI
proposeflow tui
```

## Commands

### `proposeflow init`

Initialize ProposeFlow configuration in your project.

```bash
proposeflow init [--force]
```

Creates a `proposeflow.config.ts` file with your API configuration.

Options:
- `-f, --force` - Overwrite existing config file

### `proposeflow push`

Push local schema definitions to ProposeFlow.

```bash
proposeflow push [--config <path>] [--env <name>]
```

Options:
- `-c, --config <path>` - Path to config file
- `-e, --env <name>` - Environment to use (default: development)

### `proposeflow pull`

Pull schemas from ProposeFlow and generate TypeScript/Zod types.

```bash
proposeflow pull [--config <path>] [--env <name>] [--output <path>]
```

Options:
- `-c, --config <path>` - Path to config file
- `-e, --env <name>` - Environment to use (default: development)
- `-o, --output <path>` - Output path for generated types

### `proposeflow validate`

Validate local schema definitions without pushing.

```bash
proposeflow validate [--config <path>]
```

Options:
- `-c, --config <path>` - Path to config file

### `proposeflow diff`

Show differences between local and remote schemas.

```bash
proposeflow diff [--config <path>] [--env <name>]
```

Options:
- `-c, --config <path>` - Path to config file
- `-e, --env <name>` - Environment to use (default: development)

### `proposeflow analytics`

Display tenant and schema analytics with usage metrics.

```bash
proposeflow analytics [--config <path>] [--env <name>] [--schema <name>] [--period <period>]
```

Shows summary statistics including:
- Total users and active users (daily, weekly, monthly)
- Total proposals generated
- Per-schema acceptance rates and median iterations

Options:
- `-c, --config <path>` - Path to config file
- `-e, --env <name>` - Environment to use (default: development)
- `-s, --schema <name>` - Show detailed analytics for a specific schema
- `-p, --period <period>` - Time period: `day`, `week`, or `month` (default: month)

Example output:
```
Period: Dec 19 - Jan 18

Users
────────────────────────────────────
  Total registered     125
  Monthly active       89
  Weekly active        45
  Daily active         12

Schemas
────────────────────────────────────
  Total proposals:   1,234
  Last 30 days:      456
  Avg acceptance:    78.5%

  Per schema:

  recipe@1.0.0
    Proposals: 890  Acceptance: ████████░░ 82.3%  Iterations: 1.4
```

### `proposeflow tui`

Launch the interactive terminal user interface.

```bash
proposeflow tui [--config <path>] [--env <name>] [--profile <name>]
```

The TUI provides an interactive menu to run all CLI commands. On first launch, it will prompt you to authenticate via your browser. Credentials are stored locally for future sessions.

Categories available in the TUI:
- **Schemas** - Init, validate, diff, push, pull
- **API Keys** - List and revoke API keys
- **Webhooks** - Create, list, delete endpoints
- **Usage** - View current usage and history
- **Proposals** - List, view, and decide on proposals
- **Events** - View event details
- **Account** - View status, switch profiles, logout, or login as different account

Options:
- `-c, --config <path>` - Path to config file
- `-e, --env <name>` - Environment to use (default: development)
- `-o, --output <path>` - Output path for generated types (pull)
- `-f, --force` - Overwrite existing config file (init)
- `-p, --profile <name>` - Credential profile to use (default: default)

### `proposeflow login`

Authenticate with ProposeFlow and store credentials locally.

```bash
proposeflow login [--profile <name>]
```

Opens a browser-based authentication flow. On success, credentials are saved to `~/.proposeflow/credentials.json` for future sessions.

Options:
- `-p, --profile <name>` - Profile name to store credentials under (default: default)

### `proposeflow logout`

Remove stored credentials.

```bash
proposeflow logout [--profile <name>] [--all]
```

Options:
- `-p, --profile <name>` - Profile to log out from (default: default)
- `-a, --all` - Log out from all profiles

### `proposeflow whoami`

Show current authentication status.

```bash
proposeflow whoami [--profile <name>] [--all]
```

Options:
- `-p, --profile <name>` - Profile to check (default: default)
- `-a, --all` - Show all stored profiles

### `proposeflow switch`

Switch to a different credential profile.

```bash
proposeflow switch [profile]
```

Without arguments, lists all available profiles. With a profile name, switches the default profile to that one.

Examples:
```bash
# List available profiles
proposeflow switch

# Switch to the "work" profile
proposeflow switch work
```

## Configuration

The CLI reads from `proposeflow.config.ts` in your project root:

```typescript
import { defineConfig } from '@proposeflow/cli';

export default defineConfig({
  schemas: {
    // Define schemas here or in separate files
  },
});
```

### Environment Variables

- `PROPOSEFLOW_API_URL` - API endpoint (defaults to `https://api.proposeflow.ai`)
- `PROPOSEFLOW_API_KEY` - Your API key (or use `proposeflow login` to authenticate)

## Credential Storage

The CLI stores authentication credentials in `~/.proposeflow/credentials.json`. This allows you to stay logged in across sessions without re-authenticating.

### Credential Precedence

When looking for credentials, the CLI checks in this order:

1. `PROPOSEFLOW_API_KEY` environment variable
2. `proposeflow.config.ts` in your project directory
3. `~/.proposeflow/credentials.json` (stored credentials)
4. Device code flow (prompts for browser authentication)

### Multiple Profiles

You can store credentials for multiple applications using profiles:

```bash
# Login with a named profile
proposeflow login --profile myapp

# List all profiles
proposeflow whoami --all

# Switch the default profile
proposeflow switch myapp

# Use a specific profile for a command
proposeflow tui --profile myapp
```

### Security

- Credentials are stored with `0600` permissions (owner read/write only)
- API keys can be revoked from the ProposeFlow dashboard at any time
- Use `proposeflow logout` to remove stored credentials

## Development

```bash
# Build the CLI
pnpm build

# Run in development mode
pnpm dev

# Type check
pnpm typecheck
```