Skip to content

CLI-SPEC — Simpaisa CLI Tool Specification

Status: Draft Owner: Platform Engineering Binary: simpaisa Language: Go Last Updated: 2026-04-03

1. Overview

Official CLI tool for the Simpaisa Payment Gateway. Enables developers and operations teams to interact with Pay-Ins, Pay-Outs, Remittances, and Cards from the terminal. Supports all five corridors (PK, BD, NP, IQ, EG) handling 270M+ annual transactions. Distributed via Homebrew and direct binary download.

2. Installation

# Homebrew (macOS / Linux)
brew install simpaisa/tap/simpaisa

# Direct download
curl -fsSL https://get.simpaisa.com/cli | sh

# Go install
go install github.com/simpaisa/simpaisa-cli@latest

3. Command Structure

simpaisa
├── auth
│   ├── configure          # Interactive auth setup (merchant ID, key path, environment)
│   ├── status             # Show current auth configuration
│   └── rotate-key         # Generate new RSA key pair, output public key
├── payin
│   ├── initiate           # Create a new pay-in transaction
│   ├── verify             # Verify a pay-in transaction
│   ├── status             # Check pay-in transaction status
│   └── list               # List pay-in transactions (with filters)
├── payout
│   ├── initiate           # Create a new pay-out
│   ├── status             # Check pay-out status
│   ├── batch              # Submit batch pay-out from CSV/JSON file
│   └── cancel             # Cancel a pending pay-out
├── remit
│   ├── quote              # Get remittance quote (exchange rate, fees)
│   ├── initiate           # Create a new remittance
│   ├── status             # Check remittance status
│   └── beneficiaries      # List/manage beneficiaries
├── cards
│   ├── pay                # Initiate card payment
│   ├── capture            # Capture pre-authorised payment
│   ├── void               # Void a transaction
│   └── refund             # Refund a transaction
├── webhook
│   ├── verify             # Verify a webhook signature from stdin or file
│   └── listen             # Start local webhook listener (dev mode)
├── config
│   ├── set                # Set configuration value
│   ├── get                # Get configuration value
│   └── list               # List all configuration values
└── version                # Show version, build info, API endpoint

4. Global Flags

Flag Short Description
--environment -e Override environment (sandbox/production)
--output -o Output format: json, table, yaml (default: table)
--profile -p Use named configuration profile
--verbose -v Enable verbose/debug output
--quiet -q Suppress non-essential output
--no-colour Disable coloured output
--timeout Request timeout (default: 30s)

5. Configuration File

Location: ~/.simpaisa/config.yaml

default_profile: production

profiles:
  sandbox:
    environment: sandbox
    merchant_id: MCH-001-SANDBOX
    private_key_path: ~/.simpaisa/keys/sandbox.pem
    timeout: 30s
    output_format: table

  production:
    environment: production
    merchant_id: MCH-001
    private_key_path: ~/.simpaisa/keys/production.pem
    timeout: 30s
    output_format: json
  • Profiles allow switching between environments/merchants
  • simpaisa config set default_profile sandbox
  • Environment variables override config: SIMPAISA_MERCHANT_ID, SIMPAISA_ENVIRONMENT, SIMPAISA_PRIVATE_KEY_PATH

6. Authentication

  • simpaisa auth configure — interactive wizard: prompts for merchant ID, key path, environment
  • Private key stored at ~/.simpaisa/keys/ (file permissions enforced: 0600)
  • RSA-SHA256 signing on every request (same as SDK)
  • simpaisa auth status — display current merchant ID, environment, key fingerprint
  • simpaisa auth rotate-key — generate new RSA-4096 key pair, output public key for portal upload

7. Output Formats

Table (default): 

ID              STATUS     AMOUNT    CURRENCY  CHANNEL     CREATED
txn_abc123      COMPLETED  5,000.00  PKR       EASYPAISA   2026-04-03 14:30
txn_def456      PENDING    10,000    BDT       BKASH       2026-04-03 14:31

JSON: 

{"id": "txn_abc123", "status": "COMPLETED", "amount": 5000, "currency": "PKR"}

YAML: 

id: txn_abc123
status: COMPLETED
amount: 5000
currency: PKR

  • JSON output pipeable to jq
  • Table output uses aligned columns with colour-coded status
  • --no-colour for CI/scripted usage

8. Coloured Terminal Output

  • Status colours: green (completed/success), yellow (pending), red (failed/error)
  • Automatic detection of TTY vs pipe (disable colour when piped)
  • Respect NO_COLOR environment variable (https://no-color.org/)
  • Uses fatih/color Go library

9. Shell Completions

# Bash
simpaisa completion bash > /etc/bash_completion.d/simpaisa

# Zsh
simpaisa completion zsh > "${fpath[1]}/_simpaisa"

# Fish
simpaisa completion fish > ~/.config/fish/completions/simpaisa.fish
  • Auto-complete commands, sub-commands, flags
  • Dynamic completion for transaction IDs and profiles (where practical)
  • Generated via cobra completion framework

10. Batch Operations

# Batch pay-out from CSV
simpaisa payout batch --file payouts.csv --dry-run
simpaisa payout batch --file payouts.csv --confirm

# Batch from JSON
simpaisa payout batch --file payouts.json
  • CSV format: amount,currency,beneficiary_account,beneficiary_bank,reference
  • --dry-run validates without executing
  • Progress bar for large batches
  • Summary report on completion (succeeded, failed, total amount)

11. Webhook Development

# Verify a webhook payload
echo '{"event":"payin.completed"}' | simpaisa webhook verify --secret whsec_...

# Start local listener (dev mode)
simpaisa webhook listen --port 4567 --forward http://localhost:3000/webhook
  • webhook listen starts a local HTTPS server with auto-TLS (self-signed)
  • Logs received webhooks with formatted output
  • Forwards verified payloads to local development server

12. Build and Distribution

  • Framework: cobra + viper
  • Build: goreleaser for cross-platform binaries (linux/darwin/windows, amd64/arm64)
  • CI: Bitbucket Pipelines — lint → test → build → release
  • Homebrew: simpaisa/homebrew-tap repository with formula
  • Versioning: Semantic versioning; version embedded at build time via ldflags
  • Binary size: target < 15MB (stripped, compressed)

13. Security

  • Private keys never logged or printed (only fingerprint shown)
  • Config file permissions checked on startup (warn if world-readable)
  • No credentials stored in shell history (interactive prompts for sensitive values)
  • --verbose mode redacts sensitive headers
  • Binary signed with code signing certificate

14. Testing Requirements

  • Unit tests for every command (>80% coverage)
  • Integration tests against sandbox environment
  • Golden file tests for output formatting (table, JSON, YAML)
  • Shell completion tests
  • Cross-platform build verification (linux, darwin, windows)

15. Error Handling

  • Clear error messages with suggested fix actions
  • Exit codes: 0 (success), 1 (general error), 2 (auth error), 3 (validation error), 4 (timeout)
  • --verbose flag shows full HTTP request/response for debugging
  • Actionable error messages: "Authentication failed. Run simpaisa auth configure to set up credentials."