Skip to content

README.md

Latest commit

 

History

History
174 lines (121 loc) · 4.02 KB

README.md

File metadata and controls

174 lines (121 loc) · 4.02 KB

HandCash CLI

A command-line interface tool for interacting with the HandCash API. Manage your HandCash wallet, send payments, and transfer digital items directly from your terminal.

Features

  • 🔐 Authentication - Secure login/logout with HandCash
  • 👤 Profile Management - View your HandCash profile information
  • 💰 Wallet Operations - Check balance and send payments
  • 📦 Digital Items - List and transfer blockchain-based digital items
  • 🎨 Interactive Mode - User-friendly prompts for all operations
  • 🚀 Fast & Lightweight - Built with Node.js for quick operations

Prerequisites

Installation

  1. Clone this repository:
git clone https://github.com/b0ase/handcash-cli.git
cd handcash-cli
  1. Install dependencies:
npm install
  1. Configure your HandCash credentials:
cp .env.example .env
  1. Edit .env and add your HandCash credentials:
HANDCASH_APP_ID=your-app-id-here
HANDCASH_APP_SECRET=your-app-secret-here
  1. Make the CLI globally available (optional):
npm link

Usage

Authentication

Before using any features, authenticate with HandCash:

# Login to HandCash
handcash auth login

# Check authentication status
handcash auth status

# Logout
handcash auth logout

Profile

# View your profile information
handcash profile

Wallet Operations

# Check wallet balance
handcash wallet balance

# Send a payment (interactive mode)
handcash wallet pay

# Send a payment (direct mode)
handcash wallet pay $handle 0.01 --currency BSV --description "Coffee money"

# Send payment with confirmation skip
handcash wallet pay $handle 0.01 --yes

Digital Items

# List your digital items
handcash items list
# or
handcash items ls

# Transfer items (interactive mode)
handcash items transfer

# Transfer items (direct mode)
handcash items transfer $recipient item-origin-id 1 --description "Gift for you"

Command Options

Most commands support these common options:

  • --help - Show command help
  • --yes - Skip confirmation prompts (for payments and transfers)

API Reference

Authentication Commands

  • handcash auth login [--force] - Authenticate with HandCash
  • handcash auth logout - Clear stored authentication
  • handcash auth status - Check current authentication status

Profile Commands

  • handcash profile - Display user profile information

Wallet Commands

  • handcash wallet balance - Show spendable balance
  • handcash wallet pay [destination] [amount] - Send payment
    • Options:
      • -c, --currency <currency> - Currency (BSV, USD)
      • -d, --description <description> - Payment description
      • -y, --yes - Skip confirmation

Digital Items Commands

  • handcash items list - List owned digital items
  • handcash items transfer [destination] [itemOrigin] [quantity] - Transfer items
    • Options:
      • -d, --description <description> - Transfer description
      • -y, --yes - Skip confirmation

Configuration

The CLI uses environment variables for configuration:

  • HANDCASH_APP_ID - Your HandCash application ID
  • HANDCASH_APP_SECRET - Your HandCash application secret
  • HANDCASH_ENV - Environment (defaults to 'prod')

Getting HandCash Credentials

  1. Visit dashboard.handcash.io
  2. Sign up or login to your HandCash account
  3. Create a new application
  4. Copy your App ID and App Secret to the .env file

Security Notes

  • Your App Secret should be kept secure and never shared publicly
  • Authentication tokens are stored locally in .handcash-auth
  • Use handcash auth logout to clear stored credentials

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

License

MIT License

Support

For HandCash API documentation, visit docs.handcash.io

For issues with this CLI tool, please open an issue on GitHub.