npm package: @optare/optareid-cli
Description: CLI Tool for Optare ID
Author: Optare Team
Latest version: 0.2.2

# @optare/optareid-cli

Official Command Line Interface for [Optare ID](https://id.optare.one) - The authentication platform for modern applications.

## Quick Start

### Installation

```bash
# Global installation
npm install -g @optare/optareid-cli

# Or use with npx (no installation required)
npx @optare/optareid-cli --help
```

### Setup

1. **Get your API key** from the [Optare Dashboard](https://id.optare.one/portal/settings)

2. **Set environment variable:**
```bash
export OPTARE_API_KEY="your-api-key-here"
```

3. **Verify setup:**
```bash
optare whoami
```

## Commands

### Project Initialization

#### `optare init`
Interactive setup for a new Optare project. Creates OAuth client and optionally a product for licensing.

```bash
optare init
```

**Prompts:**
- Project name
- Customer type (B2C or Enterprise)

**Generates:**
- OAuth Client ID and Secret
- Product (for Enterprise mode)
- `.env` file with credentials

---

### OAuth Client Management

#### `optare apps list`
List all OAuth applications.

```bash
optare apps list
```

#### `optare apps create`
Create a new OAuth application.

```bash
optare apps create --name "My App" --type web
```

**Options:**
- `--name <name>` - Application name (required)
- `--type <type>` - App type: `web`, `mobile`, or `service` (default: `web`)

#### `optare apps get <clientId>`
Get details of a specific application.

```bash
optare apps get client_123
```

#### `optare apps update <clientId>`
Update an application.

```bash
optare apps update client_123 --name "New Name" --add-redirect "http://localhost:3000"
```

#### `optare apps delete <clientId>`
Delete an application.

```bash
optare apps delete client_123
```

---

### Organization Management

#### `optare orgs list`
List all organizations you are a member of.

```bash
optare orgs list
```

#### `optare orgs create`
Create a new organization.

```bash
optare orgs create
```

#### `optare orgs get <orgId>`
Get organization details.

```bash
optare orgs get org_123
```

---

### API Key Management

#### `optare keys create`
Generate a new API key for server-side or CI/CD usage.

```bash
optare keys create --name "CI/CD Pipeline"
```

**Options:**
- `--name <name>` - Descriptive name for the key (required)

---

### Product Management

#### `optare product create`
Create a new product for licensing and subscriptions.

```bash
optare product create \
  --name "Pro Plan" \
  --slug "pro" \
  --description "Professional tier" \
  --features sso audit-logs advanced-analytics
```

**Options:**
- `--name <name>` - Product name (required)
- `--slug <slug>` - Unique URL-safe identifier (required)
- `--description <desc>` - Product description (optional)
- `--features <features...>` - Space-separated feature list (optional)

#### `optare product list`
List all products in your organization.

```bash
optare product list
```

#### `optare product get <slug>`
Get details of a specific product.

```bash
optare product get pro
```

---

### Subscription Management

#### `optare subscription create`
Create a new subscription for an organization.

```bash
optare subscription create \
  --organization "org_123" \
  --product "pro" \
  --seats 10 \
  --price 49.99 \
  --cycle monthly \
  --status active
```

**Options:**
- `--organization <id>` - Organization ID (required)
- `--product <id>` - Product ID or slug (required)
- `--seats <number>` - Total seat count (required)
- `--price <amount>` - Price per seat (required)
- `--cycle <cycle>` - `monthly` or `yearly` (default: `monthly`)
- `--status <status>` - `active`, `trial`, `cancelled`, or `expired` (default: `active`)
- `--endDate <date>` - Subscription end date in ISO 8601 format (optional)

#### `optare subscription list`
List all subscriptions.

```bash
optare subscription list
```

---

### Billing Management

#### `optare billing connect`
Connect a billing provider (Stripe, PayPal, or Razorpay) to your organization.

```bash
optare billing connect \
  --provider stripe \
  --secret-key "sk_live_..." \
  --webhook-secret "whsec_..."
```

**Options:**
- `--provider <provider>` - Billing provider: `stripe`, `paypal`, or `razorpay` (required)
- `--secret-key <key>` - Provider API/secret key (required)
- `--webhook-secret <secret>` - Webhook signing secret (optional)
- `--sandbox` - Use sandbox/test mode (optional)

#### `optare billing portal`
Create a self-service customer billing portal session.

```bash
optare billing portal --return-url "https://myapp.com/settings"
```

**Options:**
- `--return-url <url>` - URL to redirect after portal session (default: `http://localhost:3000`)

Opens the billing portal in your browser automatically.

---

### Utility Commands

#### `optare whoami`
Display current authenticated user information.

```bash
optare whoami
```

#### `optare dashboard`
Open the Optare Dashboard in your browser.

```bash
optare dashboard
```

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `OPTARE_API_KEY` | Your API key from the dashboard | Yes |
| `OPTARE_API_URL` | API base URL | No (defaults to `https://id.optare.one`) |
| `OPTARE_DASHBOARD_URL` | Dashboard URL for `optare dashboard` | No |

## Configuration

The CLI stores configuration in `~/.config/optare-cli/config.json` (or OS equivalent).

**Stored data:**
- API key (if saved via config, not recommended)
- Last used options

**Security:** We recommend using environment variables instead of storing the API key in config.

## Examples

### Full Project Setup

```bash
# 1. Set API key
export OPTARE_API_KEY="optk_..."

# 2. Initialize project
optare init

# 3. Create additional OAuth app for staging
optare apps:create --name "My App - Staging" --type web

# 4. Generate CI/CD key
optare keys:create --name "GitHub Actions"
```

### Enterprise Setup with Products

```bash
# Create products
optare product:create \
  --name "Starter" \
  --slug "starter" \
  --features basic-support

optare product:create \
  --name "Enterprise" \
  --slug "enterprise" \
  --features sso saml audit-logs priority-support \
  --description "Full enterprise features"

# Create subscription
optare subscription:create \
  --organization "org_xyz" \
  --product "enterprise" \
  --seats 50 \
  --price 99.99 \
  --cycle yearly
```

## Troubleshooting

### "OPTARE_API_KEY not set"

**Solution:** Export your API key:
```bash
export OPTARE_API_KEY="your-key-from-dashboard"
```

Get your key from: https://id.optare.one/portal/settings

### "Unauthorized" or 401 errors

**Causes:**
- Expired or invalid API key
- Insufficient permissions

**Solution:** Generate a new API key from the dashboard

### Command not found: optare

**Solution:** 
```bash
# Reinstall globally
npm install -g @optare/optareid-cli

# Or use npx
npx @optare/optareid-cli <command>
```

## Documentation

- [Full Documentation](https://docs.optare.one)
- [API Reference](https://docs.optare.one/api)
- [Portal Guide](https://docs.optare.one/portal-guide)

## Support

- **Issues:** [GitHub Issues](https://github.com/optare/optare-on/issues)
- **Email:** support@optare.one
- **Discord:** [Join our community](https://discord.gg/optare)

## License

MIT