@proposeflow/cli

Command-line interface for managing ProposeFlow schemas.

Installation

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

Quick Start

# 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.

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.

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.

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.

proposeflow validate [--config <path>]

Options:

• -c, --config <path> - Path to config file

proposeflow diff

Show differences between local and remote schemas.

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.

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:

  [email protected]
    Proposals: 890  Acceptance: ████████░░ 82.3%  Iterations: 1.4

proposeflow tui

Launch the interactive terminal user interface.

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.

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.

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.

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.

proposeflow switch [profile]

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

Examples:

# 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:

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:

# 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

# Build the CLI
pnpm build

# Run in development mode
pnpm dev

# Type check
pnpm typecheck