@adopture/cli/README.md

Official CLI tool for Adopture Feature Adoption Tracker - authenticate, configure projects, and manage API keys

# @adopture/cli

Official CLI tool for Adopture Feature Adoption Tracker.

## Installation

```bash
# Run directly with npx (recommended)
npx @adopture/cli@latest init

# Or install globally
npm install -g @adopture/cli
```

## Quick Start

1. **Initialize Adopture in your project:**
   ```bash
   npx @adopture/cli@latest init
   ```

2. **Install the SDK:**
   ```bash
   npm install @adopture/sdk
   ```

3. **Start tracking features:**
   ```javascript
   import { FeatureTracker } from '@adopture/sdk';

   const tracker = new FeatureTracker();
   await tracker.init(); // Automatically uses .adopture.config.json

   tracker.track('button-click', 'user-123');
   ```

## Commands

### `adopture init`
Interactive setup wizard that configures Adopture for your project.

```bash
npx @adopture/cli@latest init
```

**Options:**
- `--project-id <id>` - Specify project ID to use
- `--api-key <key>` - Specify API key to use  
- `--force` - Overwrite existing configuration

### `adopture login`
Authenticate with Adopture using your browser.

```bash
npx @adopture/cli@latest login
```

### `adopture logout`
Sign out of Adopture.

```bash
npx @adopture/cli@latest logout
```

### `adopture whoami`
Show current user information.

```bash
npx @adopture/cli@latest whoami
```

### `adopture status`
Show current project status and configuration.

```bash
npx @adopture/cli@latest status
```

### `adopture projects`
List your projects.

```bash
npx @adopture/cli@latest projects
```

### `adopture projects:create [name]`
Create a new project.

```bash
npx @adopture/cli@latest projects:create "My App"
```

## Configuration File

The CLI generates a `.adopture.config.json` file with your project configuration:

```json
{
  "projectId": "abc123-def456-ghi789",
  "projectName": "My App",
  "apiKey": "ad_live_...",
  "environment": "live",
  "apiUrl": "https://api.adopture.com"
}
```

This file is automatically used by the Adopture SDK when you call `tracker.init()` without parameters.

## Authentication

The CLI uses browser-based OAuth for secure authentication. Your credentials are stored securely in your system's credential manager (Keychain on macOS, Credential Manager on Windows, etc.).

## Environment Variables

The CLI supports the following environment variables for configuration:

### API URLs
- `ADOPTURE_API_URL` - Adopture API endpoint (default: `https://api.adopture.com`)
- `ADOPTURE_DASHBOARD_URL` - Adopture dashboard URL (default: `https://adopture.com/dashboard`)

### Legacy Variables (still supported)
- `API_URL` - Legacy API endpoint variable
- `DASHBOARD_URL` - Legacy dashboard URL variable

### Usage
```bash
# For production (default)
npx @adopture/cli login

# For custom environment
ADOPTURE_API_URL=https://api.example.com \
ADOPTURE_DASHBOARD_URL=https://example.com/dashboard \
npx @adopture/cli login

# For local development
ADOPTURE_API_URL=http://localhost:3001 \
ADOPTURE_DASHBOARD_URL=http://localhost:3000 \
npx @adopture/cli login
```

## Development

```bash
# Build the CLI
npm run build

# Development mode with watch
npm run dev

# Run locally
./bin/run.js --help
```

## Support

For help and support:
- Documentation: https://docs.adopture.com
- Issues: https://github.com/adopture/adopture/issues