Interact with the Paystack API, test webhooks locally, and manage your integration settings without leaving your command line.
npm install @toneflix/paystack-cli




The Paystack CLI helps you build, test, and manage your Paystack integration right from the terminal. Interact with the Paystack API, test webhooks locally, and manage your integration settings without leaving your command line.
- Features
- Installation
- Quick Start
- Authentication
- Commands
- Core Commands
- API Commands
- Webhook Commands
- Configuration
- Webhook Testing
- API Resources
- Examples
- Development
- Troubleshooting
- Contributing
- License
Complete Paystack API Access - Access all Paystack API endpoints directly from your terminal
Secure Authentication - Login once and securely manage your Paystack integration
Local Webhook Testing - Test webhooks locally using ngrok integration
Configuration Management - Configure API settings, timeouts, and debug modes
Beautiful Output - Formatted JSON responses with colored output for better readability
Developer Friendly - Built with TypeScript for type safety and better DX
``bash`
npm install -g @toneflix/paystack-cli
`bash`
pnpm add -g @toneflix/paystack-cli
`bash`
yarn global add @toneflix/paystack-cli
After installation, verify the CLI is installed correctly:
`bash`
paystack-cli --version
1. Initialize the CLI
`bash`
paystack-cli init
2. Login to your Paystack account
`bash`
paystack-cli login
3. Start using Paystack API commands
`bash
# List all transactions
paystack-cli transaction:list
# Fetch customer details
paystack-cli customer:fetch --id=CUS_xxxxx
# Create a new plan
paystack-cli plan:create --name="Monthly Plan" --amount=5000 --interval=monthly
`
The CLI uses your Paystack account credentials for authentication:
`bash`
paystack-cli login
You'll be prompted for:
- Email: Your Paystack account email
- Password: Your Paystack account password
- Remember: Option to save your email for future logins
After successful login, you'll select which integration to use (if you have multiple).
To logout and clear your session:
`bash`
paystack-cli logout
- Sessions automatically expire after the token timeout period
- You'll be prompted to login again when your session expires
- Login credentials are securely stored in a local SQLite database
#### init
Initialize the Paystack CLI application and setup the local database.
`bash`
paystack-cli init
#### login
Authenticate with your Paystack account.
`bash`
paystack-cli login
Options:
- Interactive prompts for email and password
- Option to remember email for faster login
- Automatic integration selection for accounts with multiple integrations
#### logout
Sign out and clear your authentication session.
`bash`
paystack-cli logout
#### config
Configure CLI settings like API base URL, timeout duration, and debug mode.
`bash`
paystack-cli config
Available configurations:
- API Base URL: Default Paystack API endpoint
- Timeout Duration: Request timeout in milliseconds
- Debug Mode: Enable/disable detailed error logging
- Ngrok Auth Token: Set ngrok authentication token for webhook testing
#### webhook listen
Start a local webhook listener using ngrok tunneling.
`bash`
paystack-cli webhook listen [local_route]
Arguments:
- local_route (optional): Your local webhook endpoint (e.g., http://localhost:8080/webhook)
Options:
- --domain, -D: Specify domain to ping (test/live) [default: test]--forward, -F
- : Forward webhook to a specific URL
Example:
`bashListen on default route
paystack-cli webhook listen
####
webhook pingSend a test webhook event to your configured webhook URL.
`bash
paystack-cli webhook ping
`Options:
-
--event, -E: Event type to simulate (charge.success, transfer.success, etc.)
- --domain, -D: Domain to ping (test/live) [default: test]
- --forward, -F: Forward to specific URL instead of saved webhookExample:
`bash
Test charge success event
paystack-cli webhook ping --event=charge.successTest transfer failed on live
paystack-cli webhook ping --event=transfer.failed --domain=live
`$3
All Paystack API endpoints are available as commands. The general format is:
`bash
paystack-cli [resource]:[action] [options]
`API Resources
The CLI provides access to the following Paystack resources:
$3
Manage payment transactions.
`bash
Initialize a transaction
paystack-cli transaction:initialize --email=customer@email.com --amount=10000List all transactions
paystack-cli transaction:list --perPage=50 --page=1Verify a transaction
paystack-cli transaction:verify --reference=xyz123View transaction details
paystack-cli transaction:view --id=123456Charge authorization
paystack-cli transaction:charge --authorization_code=AUTH_xxx --email=user@example.com --amount=5000Export transactions
paystack-cli transaction:export --from=2024-01-01 --to=2024-12-31Check authorization
paystack-cli transaction:check --authorization_code=AUTH_xxx --email=user@example.com --amount=5000Get transaction totals
paystack-cli transaction:transaction --from=2024-01-01 --to=2024-12-31Fetch transaction
paystack-cli transaction:fetch --id=12345
`$3
Manage customer information.
`bash
Create customer
paystack-cli customer:create --email=user@example.com --first_name=John --last_name=DoeUpdate customer
paystack-cli customer:update --code=CUS_xxx --first_name=JaneFetch customer
paystack-cli customer:fetch --code=CUS_xxxList customers
paystack-cli customer:list --perPage=20 --page=1Set risk action
paystack-cli customer:set_risk_action --customer=CUS_xxx --risk_action=allowDeactivate authorization
paystack-cli customer:deactivate --authorization_code=AUTH_xxx
`$3
Create and manage subscription plans.
`bash
Create plan
paystack-cli plan:create --name="Premium Plan" --amount=50000 --interval=monthlyUpdate plan
paystack-cli plan:update --code=PLN_xxx --amount=60000List plans
paystack-cli plan:list --interval=monthly --amount=50000Fetch plan
paystack-cli plan:fetch --code=PLN_xxx
`$3
Manage customer subscriptions.
`bash
Create subscription
paystack-cli subscription:create --customer=CUS_xxx --plan=PLN_xxxDisable subscription
paystack-cli subscription:disable --code=SUB_xxx --token=email_tokenEnable subscription
paystack-cli subscription:enable --code=SUB_xxx --token=email_tokenFetch subscription
paystack-cli subscription:fetch --code=SUB_xxxList subscriptions
paystack-cli subscription:list --customer=CUS_xxx --plan=PLN_xxx
`$3
Handle money transfers.
`bash
Initiate transfer
paystack-cli transfer:initiate --source=balance --amount=10000 --recipient=RCP_xxxList transfers
paystack-cli transfer:list --perPage=50Verify transfer
paystack-cli transfer:verify --reference=TRF_xxxFinalize transfer
paystack-cli transfer:finalize --transfer_code=TRF_xxx --otp=123456Bulk transfer
paystack-cli transfer:initiate --transfers='[{"amount":10000,"recipient":"RCP_xxx"}]'Disable OTP
paystack-cli transfer:disableEnable OTP
paystack-cli transfer:enableResend OTP
paystack-cli transfer:resend --transfer_code=TRF_xxx --reason=resend_otpFetch transfer
paystack-cli transfer:fetch --code=TRF_xxx
`$3
Manage transfer recipients.
`bash
Create recipient
paystack-cli transferrecipient:create --type=nuban --name="John Doe" --account_number=0123456789 --bank_code=033Update recipient
paystack-cli transferrecipient:update --code=RCP_xxx --name="Jane Doe"Delete recipient
paystack-cli transferrecipient:delete --code=RCP_xxxList recipients
paystack-cli transferrecipient:list --perPage=50
`$3
Manage split payment subaccounts.
`bash
Create subaccount
paystack-cli subaccount:create --business_name="Vendor Co" --settlement_bank=033 --account_number=0123456789 --percentage_charge=10Update subaccount
paystack-cli subaccount:update --code=ACCT_xxx --business_name="New Name"Fetch subaccount
paystack-cli subaccount:fetch --code=ACCT_xxxList subaccounts
paystack-cli subaccount:list
`$3
Create and manage payment pages.
`bash
Create page
paystack-cli page:create --name="Donation Page" --amount=5000Update page
paystack-cli page:update --code=PAGE_xxx --name="New Page Name"Fetch page
paystack-cli page:fetch --code=PAGE_xxxList pages
paystack-cli page:listCheck slug availability
paystack-cli page:check --slug=my-page
`$3
Manage payment requests and invoices.
`bash
Create payment request
paystack-cli paymentrequest:create --customer=CUS_xxx --amount=10000 --description="Invoice for services"List payment requests
paystack-cli paymentrequest:listFetch payment request
paystack-cli paymentrequest:fetch --code=PRQ_xxxUpdate payment request
paystack-cli paymentrequest:update --code=PRQ_xxx --amount=15000Verify payment request
paystack-cli paymentrequest:verify --code=PRQ_xxxSend notification
paystack-cli paymentrequest:send --code=PRQ_xxxFinalize payment request
paystack-cli paymentrequest:finalize --code=PRQ_xxxView invoice
paystack-cli paymentrequest:invoice --code=PRQ_xxx
`$3
Handle card charges and tokenization.
`bash
Submit OTP
paystack-cli charge:submit --otp=123456 --reference=ref_xxxSubmit PIN
paystack-cli charge:submit --pin=1234 --reference=ref_xxxSubmit birthday
paystack-cli charge:submit --birthday=1990-01-01 --reference=ref_xxxSubmit phone
paystack-cli charge:submit --phone=08012345678 --reference=ref_xxxTokenize charge
paystack-cli charge:tokenize --card=xxxCheck pending charge
paystack-cli charge:check --reference=ref_xxxCharge
paystack-cli charge:charge --email=user@example.com --amount=10000
`$3
Manage bulk charge operations.
`bash
Initiate bulk charge
paystack-cli bulkcharge:initiate --charges='[{"authorization":"AUTH_xxx","amount":10000}]'Fetch bulk charge
paystack-cli bulkcharge:fetch --code=BCH_xxxFetch bulk charge charges
paystack-cli bulkcharge:fetch --code=BCH_xxxPause bulk charge
paystack-cli bulkcharge:pause --code=BCH_xxxResume bulk charge
paystack-cli bulkcharge:resume --code=BCH_xxx
`$3
Process refunds for transactions.
`bash
Create refund
paystack-cli refund:create --transaction=TRX_xxx --amount=5000List refunds
paystack-cli refund:list --transaction=TRX_xxxFetch refund
paystack-cli refund:fetch --code=RFD_xxx
`$3
Get bank information.
`bash
List banks
paystack-cli bank:list --country=nigeria --use_cursor=trueResolve account number
paystack-cli bank:resolve --account_number=0123456789 --bank_code=033Resolve BVN
paystack-cli bank:resolve --bvn=12345678901Match BVN with account
paystack-cli bank:match --account_number=0123456789 --bank_code=033 --bvn=12345678901
`$3
View settlement information.
`bash
Fetch settlements
paystack-cli settlement:fetch --from=2024-01-01 --to=2024-12-31 --subaccount=ACCT_xxx
`$3
Manage integration settings.
`bash
Fetch payment session timeout
paystack-cli integration:fetchUpdate payment session timeout
paystack-cli integration:update --timeout=600
`$3
Check account balance.
`bash
Check balance
paystack-cli balance:checkView balance ledger
paystack-cli balance:balance
`$3
Verify customer information.
`bash
Resolve verification
paystack-cli verifications:resolve --verification_type=truecaller --phone=08012345678
`$3
Card information lookup.
`bash
Resolve card BIN
paystack-cli decision:resolve --bin=123456
`$3
Manage invoices.
`bash
Archive invoice
paystack-cli invoice:archive --code=INV_xxx
`Configuration
The CLI stores configuration in a local database. Use the
config command to modify settings:`bash
paystack-cli config
`$3
1. API Base URL
- Default:
https://api.paystack.co
- Change this to use a different Paystack API endpoint2. Timeout Duration
- Default:
3000ms
- HTTP request timeout in milliseconds3. Debug Mode
- Default:
false
- Enable to see detailed error messages and stack traces4. Ngrok Auth Token
- Required for webhook testing
- Get your token from ngrok.com
$3
You can also set configuration via environment variables:
-
NGROK_AUTH_TOKEN: Your ngrok authentication token
- NGROK_DOMAIN: Custom ngrok domain (if you have a paid plan)Webhook Testing
$3
1. Configure ngrok token (first time only):
`bash
paystack-cli config
# Select "Ngrok Auth Token" and enter your token
`2. Start webhook listener:
`bash
paystack-cli webhook listen http://localhost:3000/webhook
`The CLI will:
- Create an ngrok tunnel to your local server
- Update your Paystack webhook URL automatically
- Forward all webhook events to your local endpoint
$3
Send test webhook events:
`bash
Test successful charge
paystack-cli webhook ping --event=charge.successTest transfer events
paystack-cli webhook ping --event=transfer.success
paystack-cli webhook ping --event=transfer.failedTest subscription event
paystack-cli webhook ping --event=subscription.create
`$3
-
charge.success - Successful payment
- transfer.success - Successful transfer
- transfer.failed - Failed transfer
- subscription.create - New subscription createdExamples
$3
`bash
1. Initialize transaction
paystack-cli transaction:initialize \
--email=customer@example.com \
--amount=50000 \
--reference=ORDER_123452. After customer pays, verify transaction
paystack-cli transaction:verify --reference=ORDER_123453. View transaction details
paystack-cli transaction:view --id=123456
`$3
`bash
1. Create a plan
paystack-cli plan:create \
--name="Monthly Premium" \
--amount=50000 \
--interval=monthly2. Create customer
paystack-cli customer:create \
--email=subscriber@example.com \
--first_name=John \
--last_name=Doe3. Create subscription
paystack-cli subscription:create \
--customer=CUS_xxx \
--plan=PLN_xxx
`$3
`bash
1. Create transfer recipient
paystack-cli transferrecipient:create \
--type=nuban \
--name="Jane Doe" \
--account_number=0123456789 \
--bank_code=0332. Initiate transfer
paystack-cli transfer:initiate \
--source=balance \
--amount=50000 \
--recipient=RCP_xxx \
--reason="Payment for services"3. If OTP is required, finalize with OTP
paystack-cli transfer:finalize \
--transfer_code=TRF_xxx \
--otp=123456
`Development
$3
- Node.js >= 18
- PNPM (recommended) or NPM
$3
`bash
Clone repository
git clone https://github.com/toneflix/paystack-cli.git
cd paystack-cliInstall dependencies
pnpm installRun in development mode
pnpm runner [command]Build
pnpm buildRun tests
pnpm test
`$3
`md
paystack-cli/
├── src/
│ ├── Commands/ # CLI command classes
│ │ ├── Commands.ts # Dynamic API command generator
│ │ ├── InitCommand.ts
│ │ ├── LoginCommand.ts
│ │ ├── LogoutCommand.ts
│ │ ├── ConfigCommand.ts
│ │ └── WebhookCommand.ts
│ ├── Contracts/ # TypeScript interfaces
│ ├── paystack/ # Paystack API definitions
│ │ ├── apis.ts # All API endpoint schemas
│ │ └── webhooks.ts # Webhook event handlers
│ ├── utils/ # Utility functions
│ ├── cli.ts # Application entry point
│ ├── db.ts # Local database management
│ ├── helpers.ts # Helper functions
│ ├── hooks.ts # Custom hooks
│ └── Paystack.ts # Paystack API client
├── bin/ # Executable files
├── tests/ # Test files
└── package.json
`$3
- Framework: H3ravel Musket - CLI framework
- Language: TypeScript
- Database: SQLite (via better-sqlite3)
- HTTP Client: Axios
- Tunneling: ngrok
- Build Tool: tsdown
Troubleshooting
$3
1. "You're not signed in" error
`bash
Solution: Login first
paystack-cli login
`2. "Session expired" error
`bash
Solution: Login again
paystack-cli logout
paystack-cli login
`3. Webhook listener not working
`bash
Solution: Check ngrok token is configured
paystack-cli config
Select "Ngrok Auth Token" and enter your token from ngrok.com
`4. Command not found
`bash
Solution: Ensure CLI is installed globally
npm install -g @toneflix/paystack-cli
Or reinstall
npm uninstall -g @toneflix/paystack-cli
npm install -g @toneflix/paystack-cli
`5. Permission errors on macOS/Linux
`bash
Solution: Use sudo for global installation
sudo npm install -g @toneflix/paystack-cli
`$3
Enable debug mode to see detailed error information:
`bash
paystack-cli config
Select "Debug Mode" and choose "true"
`$3
For any command, you can get help by running:
`bash
paystack-cli [command] --help
`Or visit the Paystack API Documentation for API-specific information.
Contributing
Contributions are welcome! Please follow these steps:
1. Fork the repository
2. Create a feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)- Write TypeScript with proper type definitions
- Follow existing code style
- Add tests for new features
- Update documentation for API changes
- Ensure all tests pass before submitting PR
This project is licensed under the ISC License - see the LICENSE file for details.
- Email: support@toneflix.net
- Issues: GitHub Issues
- Docs: Paystack Documentation
- Community: Paystack Slack
- Built with H3ravel Musket
- Powered by Paystack
- Tunneling by ngrok
- Dev Server from H3
---
© Copyright 2026 - ToneFlix Technologies Limited