> ## Documentation Index
> Fetch the complete documentation index at: https://docs-paymentgateway.redahaloubi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Tool

> Command-line interface for testing and managing Payment Gateway

# Payment Gateway CLI

A powerful command-line interface for interacting with the Payment Gateway API. Perfect for testing, automation, and quick merchant operations without building a full integration.

<Info>
  **Current Status:** v1.1.0 - Production Ready

  Core authentication, merchant management, API keys, and payment intents with hosted checkout are fully functional.
</Info>

***

## Why Use the CLI?

<CardGroup cols={2}>
  <Card title="Rapid Testing" icon="flask">
    Test payment flows without writing code

    Instant feedback on API responses
  </Card>

  <Card title="Hosted Checkout" icon="browser">
    Create payment intents with browser checkout

    Real-time payment status polling
  </Card>

  <Card title="Developer Friendly" icon="terminal">
    Interactive prompts with validation

    Colored output, tables, and progress indicators
  </Card>

  <Card title="Multi-Environment" icon="layer-group">
    Switch between development and production

    Production-first configuration
  </Card>
</CardGroup>

***

## Installation

### Prerequisites

<Tabs>
  <Tab title="Requirements">
    **Go 1.23 or higher**

    Check your version:

    ```bash theme={null}
    go version
    # Should output: go version go1.23.x
    ```

    **Install Go:** Visit [go.dev/dl](https://go.dev/dl) or use your package manager.
  </Tab>

  <Tab title="Optional Tools">
    **Make** (optional, for easier builds)

    ```bash theme={null}
    # macOS
    xcode-select --install

    # Linux
    sudo apt install build-essential

    # Windows
    # Install via Chocolatey: choco install make
    ```
  </Tab>
</Tabs>

***

### Method 1: Install Pre-Built Binary (Recommended)

<Steps>
  <Step title="Download Latest Release">
    Download the CLI binary for your operating system:

    **Using curl:**

    ```bash theme={null}
    # Linux (AMD64)
    curl -L -o payment-cli https://github.com/rhaloubi/Payment-Gateway/releases/latest/download/Payment-Gateway-linux-amd64

    # macOS (Intel)
    curl -L -o payment-cli https://github.com/rhaloubi/Payment-Gateway/releases/latest/download/Payment-Gateway-darwin-amd64

    # macOS (Apple Silicon)
    curl -L -o payment-cli https://github.com/rhaloubi/Payment-Gateway/releases/latest/download/Payment-Gateway-darwin-arm64

    # Windows (PowerShell)
    curl.exe -L -o payment-cli.exe https://github.com/rhaloubi/Payment-Gateway/releases/latest/download/Payment-Gateway_windows_amd64.zip
    ```
  </Step>

  <Step title="Make Executable (Linux/macOS)">
    ```bash theme={null}
    chmod +x payment-cli
    ```
  </Step>

  <Step title="Move to PATH">
    **Linux/macOS:**

    ```bash theme={null}
    sudo mv payment-cli /usr/local/bin/
    ```

    **Windows:** Move `payment-cli.exe` to a directory in your PATH, or add its location to PATH.
  </Step>

  <Step title="Verify Installation">
    ```bash theme={null}
    payment-cli --version
    # Output: payment-cli version 1.1.0
    ```
  </Step>
</Steps>

***

### Method 2: Build from Source

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/rhaloubi/payment-gateway-cli.git
    cd payment-gateway-cli
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    go mod download
    ```

    This installs:

    * `cobra` - CLI framework
    * `color` - Colored terminal output
    * `tablewriter` - Table formatting
    * `spinner` - Loading animations
    * `promptui` - Interactive prompts
    * `yaml.v3` - Config file handling
  </Step>

  <Step title="Build Binary">
    **Using Go:**

    ```bash theme={null}
    go build -o payment-cli cmd/main.go
    ```

    **Using Makefile (if available):**

    ```bash theme={null}
    make build
    ```
  </Step>

  <Step title="Install Globally (Optional)">
    ```bash theme={null}
    # Linux/macOS
    sudo mv payment-cli /usr/local/bin/

    # Or use Makefile
    make install
    ```
  </Step>
</Steps>

***

## Quick Start

### Initialize CLI

<Steps>
  <Step title="Run Init Command">
    ```bash theme={null}
    payment-cli init
    ```

    **What it does:**

    * Creates config directory: `~/.payment-cli/`
    * Generates default config file with production URLs
    * Sets up environment profiles (development, production)
    * Defaults to production environment
  </Step>

  <Step title="Verify Configuration">
    ```bash theme={null}
    payment-cli config show
    ```

    **Output:**

    ```
    📋 Current Configuration
    ═══════════════════════════════════════

    🌍 Environment Settings:
      Current Environment: production
      API URL:            https://paymentgateway.redahaloubi.com
      Auth URL:           https://paymentgateway.redahaloubi.com
      Payment URL:        https://paymentgateway.redahaloubi.com

    🔐 Credentials:
      Access Token:       Not set
      User Email:         Not logged in
      Merchant ID:        Not set
      API Key:            Not set

    ⚙️  Preferences:
      Output Format:      table
      Color Enabled:      true
      Debug Mode:         false

    📁 Config File:        /Users/john/.payment-cli/config.yaml
    ```
  </Step>

  <Step title="Register and Login">
    ```bash theme={null}
    # Register new account
    payment-cli auth register

    # Login
    payment-cli auth login

    # Verify
    payment-cli whoami
    ```
  </Step>
</Steps>

***

## Core Commands

### Authentication

<Tabs>
  <Tab title="Register">
    Create a new user account:

    ```bash theme={null}
    payment-cli auth register
    ```

    **Interactive prompts:**

    ```
    Email: john@yourstore.com
    Full Name: John Merchant
    Password: ********
    Confirm Password: ********
    ```

    **Output:**

    ```
    ✅ Account created successfully!
    📧 Email: john@yourstore.com
    👤 Name: John Merchant
    🆔 User ID: 550e8400-e29b-41d4-a716-446655440000

    🚀 Next step: payment-cli auth login
    ```
  </Tab>

  <Tab title="Login">
    Authenticate and receive access token:

    ```bash theme={null}
    payment-cli auth login
    ```

    **Interactive prompts:**

    ```
    Email: john@yourstore.com
    Password: ********
    ```

    **Output:**

    ```
    ✅ Login successful!
    👤 Logged in as: john@yourstore.com

    🚀 You're ready to go! Try:
      payment-cli merchant create
    ```

    **Non-Interactive:**

    ```bash theme={null}
    payment-cli auth login --email john@yourstore.com --password SecurePass123!
    ```
  </Tab>

  <Tab title="Whoami">
    Check current authentication status:

    ```bash theme={null}
    payment-cli whoami
    ```

    **Output:**

    ```
    👤 Logged in as: john@yourstore.com
    🌍 Environment: production
    🔗 API URL: https://paymentgateway.redahaloubi.com
    ```
  </Tab>

  <Tab title="Profile">
    View detailed user profile:

    ```bash theme={null}
    payment-cli auth profile
    ```

    **Output:**

    ```
    👤 Name: John Merchant
    📧 Email: john@yourstore.com
    🆔 User ID: 550e8400-e29b-41d4-a716-446655440000
    ```
  </Tab>

  <Tab title="Change Password">
    Update your password:

    ```bash theme={null}
    payment-cli auth change-password
    ```

    **Interactive prompts:**

    ```
    Old Password: ********
    New Password: ********
    ```

    **Output:**

    ```
    ✅ Password changed successfully!
    ```
  </Tab>

  <Tab title="Logout">
    Revoke current session:

    ```bash theme={null}
    payment-cli auth logout
    ```

    **Output:**

    ```
    ✅ Logged out successfully!
    ```
  </Tab>
</Tabs>

***

### Merchant Management

<Tabs>
  <Tab title="Create Merchant">
    Create a new merchant profile:

    ```bash theme={null}
    payment-cli merchant create
    ```

    **Interactive prompts:**

    ```
    Business Name: Your Store Inc
    Legal Name: Your Store Incorporated
    all the business types: individual sole_proprietor partnership corporation non_profit
    choose one of them
    Business Type: corporation
    ```

    **Output:**

    ```
    ✅ Merchant created!
    🆔 ID: merchant_abc123def456
    📧 Email: john@yourstore.com
    🏪 Business Name: Your Store Inc
    🏢 Business Type: corporation
    🔑 Status: pending
    👤 Owner ID: 550e8400-e29b-41d4-a716-446655440000

    💡 Next: payment-cli apikey create
    ```

    **Non-Interactive:**

    ```bash theme={null}
    payment-cli merchant create \
      --business-name "Your Store Inc" \
      --legal-name "Your Store Incorporated" \
      --email "billing@yourstore.com"
    ```
  </Tab>

  <Tab title="Get Merchant">
    View merchant details:

    ```bash theme={null}
    payment-cli merchant get
    ```

    **Output:**

    ```
    🏪 ID: merchant_abc123def456
    📧 Email: billing@yourstore.com
    🏪 Business Name: Your Store Inc
    👤 Legal Name: Your Store Incorporated
    🏢 Business Type: corporation
    🔑 Status: active
    🌍 Country Code: US
    💵 Currency Code: USD
    👤 Owner ID: 550e8400-e29b-41d4-a716-446655440000
    🔑 Merchant Code: mch_xyz789abc123
    ```
  </Tab>

  <Tab title="Access Accounts">
    Switch between multiple merchant accounts:

    ```bash theme={null}
    payment-cli merchant access-accounts
    ```

    **Output:**

    ```
    ✅ Merchant account access granted!
    ```

    **With specific merchant:**

    ```bash theme={null}
    payment-cli merchant access-accounts --merchant-id merchant_abc123
    ```
  </Tab>

  <Tab title="Team Members">
    List team members for a merchant:

    ```bash theme={null}
    payment-cli merchant team
    ```

    **Output:**

    ```
    👤 ID: user_abc123
    🏪 Role Name: owner
    🔑 Status: active
    🕒 Joined At: 2026-01-24 10:00:00
    ------------------------------
    👤 ID: user_def456
    🏪 Role Name: admin
    🔑 Status: active
    🕒 Joined At: 2026-01-25 14:30:00
    ------------------------------
    ```
  </Tab>

  <Tab title="Invite User">
    Invite a team member:

    ```bash theme={null}
    payment-cli merchant invite
    ```

    **Interactive prompts:**

    ```
    please run 'payment-cli roles view' to get role name and id
    Email: teammate@example.com
    Role Name: admin
    Role ID: role_abc123
    ```

    **Output:**

    ```
    📧 Email: teammate@example.com
    🏪 Role Name: admin
    🔑 Status: pending
    🔑 Invitation Token: inv_abc123def456
    🕒 Expires At: 2026-01-31 10:00:00
    📅 Created At: 2026-01-24 10:00:00
    ```
  </Tab>

  <Tab title="List Invitations">
    View pending invitations:

    ```bash theme={null}
    payment-cli merchant invitations
    ```

    **Output:**

    ```
    📧 Email: teammate@example.com
    🏪 Role Name: admin
    🔑 Status: pending
    🕒 Expires At: 2026-01-31 10:00:00
    🔑 Token: inv_abc123def456
    ------------------------------
    ```
  </Tab>

  <Tab title="Settings">
    View merchant settings:

    ```bash theme={null}
    payment-cli merchant setting
    ```

    **Output:**

    ```
    💵 Default Currency: USD
    📝 Statement Descriptor: YOUR STORE INC
    📧 Notification Email: billing@yourstore.com
    📨 Send Email Receipts: true
    💰 Auto Settle: true
    📅 Settle Schedule: daily
    ```
  </Tab>
</Tabs>

***

### API Key Management

<Tabs>
  <Tab title="Create API Key">
    Generate a new API key for payment processing:

    ```bash theme={null}
    payment-cli apikey create
    ```

    **Interactive prompt:**

    ```
    API Key Name: Production Server Key
    ```

    **Output:**

    ```
    ✅ API key created!
    🔑 API Key: Production Server Key
    Please copy the plain key, it will not be shown again
    🔑 Plain Key: pk_live_abc123def456ghi789jkl012mno345pqr678
    ```

    <Warning>
      **IMPORTANT:** Save this key immediately! It cannot be retrieved again.
    </Warning>
  </Tab>

  <Tab title="Store API Key">
    Store API key locally for CLI usage:

    ```bash theme={null}
    payment-cli apikey store pk_live_abc123def456ghi789jkl012mno345pqr678
    ```

    **Output:**

    ```
    ✅ API key stored!
    ```

    The key is now saved in your config file and will be used automatically for payment operations.
  </Tab>
</Tabs>

***

### Roles Management

<Tabs>
  <Tab title="View Roles">
    List all available roles:

    ```bash theme={null}
    payment-cli roles view
    ```

    **Output:**

    ```
    🔑 Role ID: role_abc123
    👤 Role: owner
    📝 Description: Full access to merchant account
    🔑 Role ID: role_def456
    👤 Role: admin
    📝 Description: Administrative access
    🔑 Role ID: role_ghi789
    👤 Role: developer
    📝 Description: API access only
    ```
  </Tab>
</Tabs>

***

### Configuration Management

<Tabs>
  <Tab title="Show Config">
    Display complete configuration:

    ```bash theme={null}
    payment-cli config show
    ```

    **Output:**

    ```
    📋 Current Configuration
    ═══════════════════════════════════════

    🌍 Environment Settings:
      Current Environment: production
      API URL:            https://paymentgateway.redahaloubi.com
      Auth URL:           https://paymentgateway.redahaloubi.com
      Payment URL:        https://paymentgateway.redahaloubi.com

    🔐 Credentials:
      Access Token:       eyJhbGci...XVCJ9 (truncated)
      User Email:         john@yourstore.com
      Merchant ID:        merchant_abc123def456
      API Key:            pk_live_ab...r678 (truncated)

    ⚙️  Preferences:
      Output Format:      table
      Color Enabled:      true
      Debug Mode:         false

    📁 Config File:        /Users/john/.payment-cli/config.yaml
    ```
  </Tab>

  <Tab title="Set Preference">
    Modify configuration preferences:

    ```bash theme={null}
    # Change output format
    payment-cli config set output_format json

    # Enable debug mode
    payment-cli config set debug_mode true

    # Disable colors
    payment-cli config set color_enabled false
    ```

    **Available keys:**

    * `output_format` - Values: table, json, yaml
    * `color_enabled` - Values: true, false
    * `debug_mode` - Values: true, false

    **Output:**

    ```
    ✅ Set output_format = json
    ```
  </Tab>

  <Tab title="Switch Environment">
    Change between production and development:

    ```bash theme={null}
    payment-cli config use development
    ```

    **Interactive selection:**

    ```
    Select Environment:
    ▸ production
      development
    ```

    **Output:**

    ```
    ✅ Switched to development environment
    🔗 API URL: http://localhost:8080
    ```

    **Switch back to production:**

    ```bash theme={null}
    payment-cli config use production
    ```
  </Tab>

  <Tab title="Reset Config">
    Reset all configuration to defaults:

    ```bash theme={null}
    payment-cli config reset
    ```

    **Confirmation prompt:**

    ```
    Are you sure you want to reset all configuration? This will clear credentials: (y/N)
    ```

    **Output:**

    ```
    ✅ Configuration reset to defaults
    🚀 Run 'payment-cli init' to reinitialize if needed
    ```
  </Tab>
</Tabs>

***

## Payment Operations

### Payment Intents (Hosted Checkout)

<Info>
  Payment Intents provide a hosted checkout page where customers can securely enter their payment details. The CLI opens the checkout in your browser and polls for completion.
</Info>

<Tabs>
  <Tab title="Create Intent">
    Create a payment intent with hosted checkout:

    ```bash theme={null}
    payment-cli payment intent create
    ```

    **Interactive prompts:**

    ```
    💳 Create Payment Intent
    ═══════════════════════════════════════

    Amount (in cents): 5000
    Currency:
    ▸ USD
      EUR
      MAD
    Description (optional, press enter to skip): Premium Plan Subscription
    Customer Email (optional, press enter to skip): customer@example.com
    Capture Method:
    ▸ automatic
      manual
    ```

    **Output:**

    ```
    ✅ Payment intent created!

    📋 Payment Intent Details:
      ID:          pi_abc123def456ghi789
      Amount:      5000 USD ($50.00 USD)
      Status:      created
      Description: Premium Plan Subscription
      Expires:     2026-01-26 15:30:00

    🌐 Checkout URL:
      https://checkout-page-amber.vercel.app/checkout/pi_abc123def456?client_secret=...

    🚀 Opening checkout page in your browser...
    💡 Complete the payment in your browser

    ⏳ Waiting for payment completion...
       (Press Ctrl+C to cancel polling)
    ```

    **After customer completes payment:**

    ```
    ✅ Payment completed successfully!

    📋 Payment Details:
      Intent ID:  pi_abc123def456ghi789
      Status:     authorized
      Payment ID: pay_xyz789uvw012rst345

    🎉 Transaction complete!
    ```
  </Tab>

  <Tab title="With Flags">
    Create intent with command-line flags:

    ```bash theme={null}
    payment-cli payment intent create \
      --amount 5000 \
      --currency USD \
      --email customer@example.com \
      --description "Order #12345" \
      --capture automatic
    ```

    This bypasses interactive prompts and immediately creates the intent.
  </Tab>
</Tabs>

<Note>
  **How Payment Intent Polling Works:**

  1. CLI creates payment intent via API
  2. Browser opens automatically with checkout URL
  3. Customer enters payment details on hosted page
  4. CLI polls payment status every 3 seconds
  5. Shows success/failure when payment completes
  6. Times out after 15 minutes if no completion

  The checkout page handles all PCI compliance and security.
</Note>

***

### Direct Payment Authorization

<Tabs>
  <Tab title="Authorize Payment">
    Authorize a payment directly (without hosted checkout):

    ```bash theme={null}
    payment-cli payment authorize
    ```

    **Interactive prompts:**

    ```
    💳 Payment Authorization
    -----------------------
    Amount (in cents): 5000
    Currency:
    ▸ USD
      EUR
      MAD
    Card Number: 4242424242424242
    Cardholder Name: John Doe
    Expiration Month:
    ▸ 01 02 03 04 05 06 07 08 09 10 11 12
    Expiration Year: 2027
    CVV: ***
    Customer Email: customer@example.com
    ```

    **Output:**

    ```
    🧾 Payment details collected successfully
    Authorization ID: pay_abc123def456
    Status: authorized
    Amount: 50 USD
    Card Brand: visa
    Card Last 4: •••• 4242
    Auth Code: 123456
    Fraud Decision: approve
    Response Message: Approved
    Transaction ID: txn_xyz789abc123
    ```
  </Tab>
</Tabs>

***

### Transaction Management

<Tabs>
  <Tab title="List Transactions">
    View all transactions:

    ```bash theme={null}
    payment-cli payment transactions
    ```

    **Interactive prompts:**

    ```
    Limit (press enter for default): 10
    Offset (press enter for default): 0
    Filter by status:
    ▸ All (default)
      Authorized
      Voided
      Captured
      Refunded
    ```

    **Output:**

    ```
    Transaction ID: txn_abc123
    Status: authorized
    Amount: 50 USD
    Card Brand: visa
    Card Last 4: •••• 4242
    -----------------------
    Transaction ID: txn_def456
    Status: captured
    Amount: 75 EUR
    Card Brand: mastercard
    Card Last 4: •••• 5555
    -----------------------
    ```
  </Tab>

  <Tab title="Capture">
    Capture a previously authorized payment:

    ```bash theme={null}
    payment-cli payment capture
    ```

    **Output:**

    ```
    💳 Payment Capture
    ⚠️  Please go to the Payment Gateway Dashboard to capture the payment!
    ```
  </Tab>

  <Tab title="Void">
    Void an authorized payment:

    ```bash theme={null}
    payment-cli payment void
    ```

    **Output:**

    ```
    💳 Payment Void
    ⚠️  Please go to the Payment Gateway Dashboard to void the payment!
    ```
  </Tab>

  <Tab title="Refund">
    Refund a captured payment:

    ```bash theme={null}
    payment-cli payment refund
    ```

    **Output:**

    ```
    💳 Payment Refund
    ⚠️  Please go to the Payment Gateway Dashboard to refund the payment!
    ```
  </Tab>
</Tabs>

***

## Advanced Features

### Health Check

Verify API connectivity:

```bash theme={null}
payment-cli health
```

**Output:**

```
✅ CLI is working!
```

***

### Debug Mode

Enable verbose logging for troubleshooting:

```bash theme={null}
payment-cli --debug merchant list
```

Or enable globally:

```bash theme={null}
payment-cli config set debug_mode true
```

***

### Output Formats

<Tabs>
  <Tab title="Table (Default)">
    Human-readable tables:

    ```bash theme={null}
    payment-cli --output table merchant list
    ```
  </Tab>

  <Tab title="JSON">
    Machine-readable output for scripts:

    ```bash theme={null}
    payment-cli --output json merchant list
    ```

    ```json theme={null}
    {
      "success": true,
      "data": {
        "merchants": [
          {
            "id": "merchant_abc123",
            "business_name": "Your Store Inc",
            "status": "active"
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="YAML">
    Human-readable structured output:

    ```bash theme={null}
    payment-cli --output yaml merchant list
    ```

    ```yaml theme={null}
    success: true
    data:
      merchants:
        - id: merchant_abc123
          business_name: Your Store Inc
          status: active
    ```
  </Tab>
</Tabs>

***

## Example Workflows

### Workflow 1: Complete Setup

From zero to payment-ready in 3 minutes:

```bash theme={null}
# 1. Initialize
payment-cli init

# 2. Register account
payment-cli auth register

# 3. Login
payment-cli auth login

# 4. Create merchant
payment-cli merchant create

# 5. Generate API key
payment-cli apikey create

# 6. Store API key
payment-cli apikey store pk_live_your_key_here

# 7. Create test payment intent
payment-cli payment intent create
```

***

### Workflow 2: Testing Payment Flow

Test a complete payment with hosted checkout:

```bash theme={null}
# 1. Ensure you're logged in
payment-cli whoami

# 2. Verify API key is set
payment-cli config show

# 3. Create payment intent
payment-cli payment intent create

# 4. Complete payment in browser
# (CLI automatically opens checkout page)

# 5. View transaction
payment-cli payment transactions
```

***

### Workflow 3: Environment Switching

Switch between development and production:

```bash theme={null}
# Work on production
payment-cli config use production
payment-cli merchant create

# Switch to local dev
payment-cli config use development
payment-cli payment intent create

# Back to production
payment-cli config use production
```

***

## Configuration File

The CLI stores configuration in `~/.payment-cli/config.yaml`:

```yaml theme={null}
# Current active environment
current_env: production

# Environment definitions
environments:
  production:
    api_url: https://paymentgateway.redahaloubi.com
    auth_url: https://paymentgateway.redahaloubi.com
    payment_url: https://paymentgateway.redahaloubi.com
  
  development:
    api_url: http://localhost:8080
    auth_url: http://localhost:8080
    payment_url: http://localhost:8080

# Credentials (auto-managed)
credentials:
  access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  refresh_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  user_email: john@yourstore.com
  merchant_id: merchant_abc123def456
  api_key: pk_live_abc123def456ghi789jkl012mno345pqr678

# User preferences
preferences:
  output_format: table  # table | json | yaml
  color_enabled: true
  debug_mode: false
```

<Warning>
  **Security Note:**

  The config file contains your access token and API key. Protect it like a password:

  ```bash theme={null}
  # Set restrictive permissions (Linux/macOS)
  chmod 600 ~/.payment-cli/config.yaml

  # Don't commit to version control
  echo ".payment-cli/" >> ~/.gitignore
  ```
</Warning>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="'payment-cli: command not found'">
    **Cause:** Binary not in PATH

    **Solutions:**

    **Option 1: Move to PATH**

    ```bash theme={null}
    sudo mv payment-cli /usr/local/bin/
    ```

    **Option 2: Run from current directory**

    ```bash theme={null}
    ./payment-cli --help
    ```

    **Option 3: Add to PATH**

    ```bash theme={null}
    export PATH=$PATH:$(pwd)
    ```
  </Accordion>

  <Accordion title="'config file not found'">
    **Cause:** CLI not initialized

    **Solution:**

    ```bash theme={null}
    payment-cli init
    ```

    **Verify:**

    ```bash theme={null}
    ls -la ~/.payment-cli/
    # Should show config.yaml
    ```
  </Accordion>

  <Accordion title="'connection refused' errors">
    **Cause:** Wrong environment or API server not reachable

    **Solutions:**

    **Check environment:**

    ```bash theme={null}
    payment-cli config show
    # Verify API URL is correct
    ```

    **Switch to production:**

    ```bash theme={null}
    payment-cli config use production
    ```

    **Test connectivity:**

    ```bash theme={null}
    payment-cli health
    ```
  </Accordion>

  <Accordion title="'unauthorized' errors">
    **Cause:** Not logged in or token expired

    **Solution:**

    ```bash theme={null}
    # Check login status
    payment-cli whoami

    # Login if needed
    payment-cli auth login
    ```
  </Accordion>

  <Accordion title="'API key not set'">
    **Cause:** No API key stored in config

    **Solution:**

    ```bash theme={null}
    # Create API key
    payment-cli apikey create

    # Store the key
    payment-cli apikey store pk_live_your_key_here

    # Verify
    payment-cli config show
    ```
  </Accordion>

  <Accordion title="Browser doesn't open for payment intents">
    **Cause:** Platform not supported or browser not available

    **Solution:** The checkout URL is displayed in the terminal. Copy and paste it into your browser manually. The CLI will still poll for payment completion.
  </Accordion>

  <Accordion title="Payment intent polling timeout">
    **Cause:** Payment took longer than 15 minutes

    **Solution:** Check your merchant dashboard for payment status, or create a new payment intent.
  </Accordion>
</AccordionGroup>

***

## Scripting & Automation

### Bash Script Example

```bash theme={null}
#!/bin/bash

# Automated merchant setup script
echo "🚀 Setting up new merchant..."

# Login
payment-cli auth login --email $ADMIN_EMAIL --password $ADMIN_PASSWORD

# Create merchant
echo "Creating merchant..."
payment-cli merchant create \
  --business-name "New Store" \
  --legal-name "New Store LLC" \
  --email "billing@newstore.com"

# Create API key
echo "Generating API key..."
payment-cli apikey create

echo "✅ Setup complete!"
echo "💡 Don't forget to store your API key:"
echo "payment-cli apikey store <your_key>"
```

***

### CI/CD Integration

```yaml theme={null}
# GitHub Actions example
name: Test Payment Integration

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      
      - name: Install Payment CLI
        run: |
          curl -L -o payment-cli https://github.com/rhaloubi/payment-gateway-cli/releases/latest/download/payment-cli-linux-amd64
          chmod +x payment-cli
          sudo mv payment-cli /usr/local/bin/
      
      - name: Initialize CLI
        run: |
          payment-cli init
          payment-cli config use production
      
      - name: Test Authentication
        run: |
          payment-cli auth login \
            --email ${{ secrets.TEST_EMAIL }} \
            --password ${{ secrets.TEST_PASSWORD }}
          payment-cli whoami
      
      - name: Verify Merchant Access
        run: |
          payment-cli merchant get
```

***

## Command Reference

### Complete Command List

<Accordion title="payment-cli init">
  Initialize CLI configuration

  **Usage:** `payment-cli init`

  Creates config directory and default settings file.
</Accordion>

<Accordion title="payment-cli auth register">
  Register new user account

  **Usage:** `payment-cli auth register [--email EMAIL] [--name NAME] [--password PASSWORD]`

  **Interactive:** If flags omitted, prompts for input
</Accordion>

<Accordion title="payment-cli auth login">
  Authenticate user

  **Usage:** `payment-cli auth login [--email EMAIL] [--password PASSWORD]`

  **Interactive:** If flags omitted, prompts for input
</Accordion>

<Accordion title="payment-cli auth logout">
  Revoke current session

  **Usage:** `payment-cli auth logout`
</Accordion>

<Accordion title="payment-cli whoami">
  Show current user info

  **Usage:** `payment-cli whoami`
</Accordion>

<Accordion title="payment-cli auth profile">
  Show detailed user profile

  **Usage:** `payment-cli auth profile`
</Accordion>

<Accordion title="payment-cli auth change-password">
  Change user password

  **Usage:** `payment-cli auth change-password [--old-password OLD] [--new-password NEW]`
</Accordion>

<Accordion title="payment-cli merchant create">
  Create new merchant

  **Usage:** `payment-cli merchant create [FLAGS]`

  **Flags:**

  * `--business-name`: Business name
  * `--legal-name`: Legal name
  * `--email`: Business email
</Accordion>

<Accordion title="payment-cli merchant get">
  Get merchant details

  **Usage:** `payment-cli merchant get`
</Accordion>

<Accordion title="payment-cli merchant access-accounts">
  Access merchant accounts

  **Usage:** `payment-cli merchant access-accounts [--merchant-id ID]`
</Accordion>

<Accordion title="payment-cli merchant team">
  List team members

  **Usage:** `payment-cli merchant team`
</Accordion>

<Accordion title="payment-cli merchant invite">
  Invite team member

  **Usage:** `payment-cli merchant invite`
</Accordion>

<Accordion title="payment-cli merchant invitations">
  List pending invitations

  **Usage:** `payment-cli merchant invitations`
</Accordion>

<Accordion title="payment-cli merchant setting">
  View merchant settings

  **Usage:** `payment-cli merchant setting`
</Accordion>

<Accordion title="payment-cli apikey create">
  Create new API key

  **Usage:** `payment-cli apikey create`
</Accordion>

<Accordion title="payment-cli apikey store">
  Store API key locally

  **Usage:** `payment-cli apikey store <plain_key>`
</Accordion>

<Accordion title="payment-cli roles view">
  View all available roles

  **Usage:** `payment-cli roles view`
</Accordion>

<Accordion title="payment-cli payment intent create">
  Create payment intent with hosted checkout

  **Usage:** `payment-cli payment intent create [FLAGS]`

  **Flags:**

  * `--amount, -a`: Amount in cents
  * `--currency, -c`: Currency (USD, EUR, MAD)
  * `--email, -e`: Customer email
  * `--description, -d`: Payment description
  * `--capture`: Capture method (automatic/manual)
  * `--order-id`: Your internal order ID
</Accordion>

<Accordion title="payment-cli payment authorize">
  Authorize payment directly

  **Usage:** `payment-cli payment authorize`
</Accordion>

<Accordion title="payment-cli payment transactions">
  List transactions

  **Usage:** `payment-cli payment transactions`
</Accordion>

<Accordion title="payment-cli payment capture">
  Capture payment (dashboard only)

  **Usage:** `payment-cli payment capture`
</Accordion>

<Accordion title="payment-cli payment void">
  Void payment (dashboard only)

  **Usage:** `payment-cli payment void`
</Accordion>

<Accordion title="payment-cli payment refund">
  Refund payment (dashboard only)

  **Usage:** `payment-cli payment refund`
</Accordion>

<Accordion title="payment-cli config show">
  Show current configuration

  **Usage:** `payment-cli config show`
</Accordion>

<Accordion title="payment-cli config set">
  Set configuration value

  **Usage:** `payment-cli config set <key> <value>`

  **Keys:** output\_format, color\_enabled, debug\_mode
</Accordion>

<Accordion title="payment-cli config use">
  Switch environment

  **Usage:** `payment-cli config use <environment>`

  **Environments:** production, development
</Accordion>

<Accordion title="payment-cli config reset">
  Reset configuration to defaults

  **Usage:** `payment-cli config reset`
</Accordion>

<Accordion title="payment-cli health">
  Check CLI and API health

  **Usage:** `payment-cli health`
</Accordion>

***

## Global Flags

<ParamField type="boolean">
  Enable debug output with verbose logging

  **Usage:** `payment-cli --debug merchant list`
</ParamField>

<ParamField type="string">
  Output format

  **Values:** table, json, yaml

  **Default:** table

  **Usage:** `payment-cli -o json merchant list`
</ParamField>

<ParamField type="string">
  Config file path (default: \~/.payment-cli/config.yaml)

  **Usage:** `payment-cli --config /custom/path/config.yaml merchant list`
</ParamField>

<ParamField type="boolean">
  Show help for any command

  **Usage:** `payment-cli merchant --help`
</ParamField>

<ParamField type="boolean">
  Show CLI version

  **Usage:** `payment-cli --version`
</ParamField>

***

## Tips & Best Practices

<AccordionGroup>
  <Accordion title="Production by Default" icon="shield-check">
    The CLI defaults to production environment for safety. If you're testing locally:

    ```bash theme={null}
    payment-cli config use development
    ```
  </Accordion>

  <Accordion title="Secure Your API Keys" icon="key">
    Never commit API keys to version control:

    ```bash theme={null}
    # Add to .gitignore
    echo ".payment-cli/" >> .gitignore
    echo "*.key" >> .gitignore
    ```
  </Accordion>

  <Accordion title="Use Environment Variables" icon="code">
    For CI/CD, use environment variables instead of storing credentials in config:

    ```bash theme={null}
    export PAYMENT_CLI_EMAIL=john@yourstore.com
    export PAYMENT_CLI_PASSWORD=SecurePass123!

    payment-cli auth login --email $PAYMENT_CLI_EMAIL --password $PAYMENT_CLI_PASSWORD
    ```
  </Accordion>

  <Accordion title="Test Payment Intents" icon="flask">
    Use test card numbers for testing payment intents:

    * **Success:** 4242 4242 4242 4242
    * **Decline:** 4000 0000 0000 0002
    * **Expired:** 4000 0000 0000 0069

    Any future expiry date and any 3-digit CVV will work.
  </Accordion>

  <Accordion title="Monitor Payment Status" icon="chart-line">
    The CLI polls payment status automatically, but you can also check your merchant dashboard for real-time updates.
  </Accordion>
</AccordionGroup>

***

## What's New in v1.1.0

<CardGroup cols={2}>
  <Card title="Payment Intents" icon="credit-card">
    Create payment intents with hosted checkout

    Browser-based payment flow with automatic polling
  </Card>

  <Card title="Enhanced Config" icon="gear">
    Production-first configuration

    Easy environment switching
  </Card>

  <Card title="Better UX" icon="sparkles">
    Improved error messages and feedback

    Real-time status updates
  </Card>

  <Card title="More Commands" icon="terminal">
    Config set/use/reset commands

    Roles management
  </Card>
</CardGroup>

***

## Support

Need help? We're here for you:

* **Documentation:** [docs-paymentgateway.redahaloubi.com](https://docs-paymentgateway.redahaloubi.com)
* **Email:** [redahaloubi8@gmail.com](mailto:redahaloubi8@gmail.com)
* **Issues:** [GitHub Issues](https://github.com/rhaloubi/payment-gateway-cli/issues)

***

## License

MIT License - See LICENSE file for details.

***

\*\*Built with ❤️ for \*\*[**Reda haloubi**](https://www.redahaloubi.com/)
