███████  █████  ██████  ██      ██ ██   ██
  ██      ██   ██ ██   ██ ██      ██ ██  ██
  ███████ ███████ ██████  ██      ██ █████
       ██ ██   ██ ██      ██      ██ ██  ██
  ███████ ██   ██ ██      ███████ ██ ██   ██
═══════════════════════════════════════════════
  SAPLIY CLI · DEVELOPER COMMAND LINE
  auth · zones · listen · trigger · webhooks
  payments · playbook · debug · connect · run
═══════════════════════════════════════════════

Sapliy is an AI-native Financial Operations Intelligence Layer that turns business goals into reliable, explainable, auditable financial outcomes — by orchestrating the systems companies already run (Stripe, PayPal, Paddle, HubSpot, Xero), not replacing them.

---

What is this?

This repository is the developer command-line tool for the Sapliy platform — the fastest way to authenticate against a Sapliy gateway, manage zones, stream webhook events to your machine (no tunnels), trigger test events, scaffold local zone/flow configs, and bootstrap Operational Playbooks. It is written in Go, uses the official Go SDK (github.com/sapliy/sapliy-sdk-go), and talks to the core backend (sapliy-ecosystem) over the public gateway API.

---

Key features

• 🔑 Authentication — interactive login with your Sapliy API key (sapliy auth login); config persisted to ~/.sapliy.yaml.
• 🎧 Webhook listening — stream events locally with an optional event-pattern filter and signature verification (no ngrok needed).
• ⚡ Event triggering — fire test events (e.g. payment.failed) into a zone from the terminal.
• 🗂️ Zone management — list, create, and switch zones (test/live modes).
• 📦 Webhook ops — list, inspect, replay, and bulk-replay failed webhook deliveries.
• 💳 Payment intents — create payment intents (amounts in cents) via the SDK.
• 📋 Playbook bootstrap — sapliy playbook list and sapliy playbook bootstrap <type> for the three MVP Operational Playbooks.
• 🖥️ Embedded console — sapliy run serves the self-contained Sapliy Automation Studio UI locally with an API proxy.

---

Installation

From source

go install github.com/sapliy/sapliy-cli/cmd/sapliy@latest

Build locally

git clone https://github.com/Sapliy/sapliy-cli.git
cd sapliy-cli

make build    # builds ./sapliy
sudo make install   # installs to /usr/local/bin

---

Quickstart

# 1. Log in with your API key (interactive prompt)
sapliy auth login

# 2. Set your organization, then list zones
export SAPLIY_ORG_ID=org_abc123
sapliy zones list

# 3. Switch to your zone
sapliy zones switch zone_test_abc123

# 4. Listen for webhooks locally (HTTP server on :3000 by default)
sapliy listen

# 5. In another terminal, trigger a test event for the Revenue Recovery playbook
sapliy trigger payment.failed --zone zone_test_abc123 --data '{"amount": 2000}'

# 6. Bootstrap a playbook scaffold
sapliy playbook list
sapliy playbook bootstrap revenue-recovery

The CLI reads config from ~/.sapliy.yaml and environment variables prefixed with SAPLIY_.

---

Architecture / How it works

A Cobra command tree wired to the Go SDK. Each command resolves the API key, base URL, and zone from Viper (config file + SAPLIY_* env), then calls the corresponding SDK service — or runs a local-only feature (listen, debug, run, generate).

flowchart TD
    CLI["sapliy"]
    CLI --> auth["auth login"]
    CLI --> zones["zones list · create · switch"]
    CLI --> listen["listen [pattern] --port"]
    CLI --> trigger["trigger <event> --zone --data"]
    CLI --> webhooks["webhooks list · inspect · replay · replay-failed"]
    CLI --> payments["payments create --amount --currency"]
    CLI --> playbook["playbook list · bootstrap"]
    CLI --> debug["debug listen · inspect · repl"]
    CLI --> connect["connect <ws-url> --key"]
    CLI --> generate["generate zone · flow"]
    CLI --> templates["templates list · show · apply"]
    CLI --> run["run — embedded Automation Studio"]
    CLI --> version["version"]

    auth --> CFG["~/.sapliy.yaml"]
    zones --> CFG
    playbook --> CAT["static MVP catalog<br/>revenue-recovery · refund-approval · invoice-reminders"]
    trigger -->|"SAPLIY_API_URL (default :8080)"| GW["sapliy-ecosystem Gateway"]
    webhooks --> GW
    payments --> GW
    connect -->|"WebSocket event bus"| GW
    run -->|"API proxy to gateway"| GW

Loading

---

Commands

Authentication

sapliy auth login          # prompts for your API key

Zones

sapliy zones list                        # requires SAPLIY_ORG_ID
sapliy zones create -n "My Zone" -m test
sapliy zones switch <zone_id>

Webhook listening

sapliy listen                  # all events, port 3000
sapliy listen payment.*        # filter by event pattern
sapliy listen --port 3001      # custom port

listen verifies the X-Sapliy-Signature header when SAPLIY_WEBHOOK_SECRET is set and pretty-prints JSON payloads.

Triggering events

sapliy trigger payment.failed --zone zone_test_abc123
sapliy trigger payment.succeeded --zone zone_test_abc123 --data '{"amount": 5000}'

Webhooks

sapliy webhooks list --zone zone_test_abc123 --limit 20
sapliy webhooks inspect <event_id>
sapliy webhooks replay <event_id> --force
sapliy webhooks replay-failed --since 24h --dry-run

Payments

sapliy payments create --amount 2000 --currency USD    # amount in cents

Playbooks

sapliy playbook list
# 📋 Sapliy Operational Playbooks
# revenue-recovery      Recover failed subscription payments with automated dunning and smart retries
# refund-approval       Route refunds and invoice adjustments through the policy engine for approval
# invoice-reminders     Send automated reminders for overdue invoices

sapliy playbook bootstrap revenue-recovery     # prints a JSON scaffold config

Debug & connect

sapliy debug listen --zone zone_test_abc123 --verbose
sapliy debug inspect <flow_id>
sapliy debug repl                             # interactive event-testing REPL
sapliy connect ws://localhost:8080/ws --key sk_test_...

Scaffolding & templates

sapliy generate zone myzone                   # writes myzone.zone.json
sapliy generate flow myflow                   # writes myflow.flow.json
sapliy templates list
sapliy templates apply sapliy-basic

Local console

sapliy run --port 3000 --api http://localhost:8080   # serves the embedded Automation Studio UI + API proxy

---

Configuration

Variable	Description
SAPLIY_API_KEY	API key for non-interactive use
SAPLIY_API_URL	API gateway URL (default: http://localhost:8080)
SAPLIY_ORG_ID	Organization ID (required for zones list / zones create)
SAPLIY_ZONE	Default zone ID (current_zone)
SAPLIY_WEBHOOK_SECRET	Enables webhook signature verification in listen

Config is persisted to ~/.sapliy.yaml; a custom path can be passed with --config.

---

Operational Playbooks

The CLI is the fastest way to drive the MVP playbooks from code: sapliy trigger payment.failed feeds the Revenue Recovery & Dunning engine, sapliy trigger refund.requested exercises the Refund Approval policy gates, and sapliy playbook bootstrap scaffolds the config for any of the three (Revenue Recovery, Refund Approval, Invoice Reminders). The decision outcomes can be inspected in the console's Audit Decision Log view or the backend's hash-chained decision log.

---

Development

make build                 # go build -o sapliy ./cmd/sapliy
go test ./...              # unit tests (incl. playbook catalog/bootstrap)
GOWORK=off go build ./...  # build when working inside the multi-repo workspace
go vet ./...               # static checks

• Stack — Go 1.25+, Cobra, Viper, and the official Go SDK (github.com/sapliy/sapliy-sdk-go, locally replaced via replace in go.mod).
• Conventions — one file per command group in pkg/cmd/; feature commands get a matching *_test.go.

---

License

MIT. See LICENSE.

Links

• Docs — Sapliy documentation site (/cli, /sdks/go)
• GitHub — github.com/Sapliy
• Related repos — sapliy-ecosystem (backend) · sapliy-sdk-go · sapliy-automation (console) · sapliy-integrations (connectors)