@ktmcp-cli/billingo 1.0.0 → 1.0.1

package/README.md

@@ -1,378 +1,199 @@
-# Billingo CLI
+# Billingo API CLI
 
-<p align="center">
-  <img src="banner.png" alt="KTMCP Banner" width="100%">
-</p>
+> "Six months ago, everyone was talking about MCPs. And I was like, screw MCPs. Every MCP would be better as a CLI."
+>
+> — [Peter Steinberger](https://twitter.com/steipete), Founder of OpenClaw
+> [Watch on YouTube (~2:39:00)](https://www.youtube.com/@lexfridman) | [Lex Fridman Podcast #491](https://lexfridman.com/peter-steinberger/)
 
+A production-ready command-line interface for the Billingo API v3. Manage invoices, partners, products, and bank accounts for Hungarian businesses directly from your terminal.
 
-Production-ready command-line interface for the [Billingo API v3](https://www.billingo.hu/) - Hungarian invoicing and billing automation.
+> **Disclaimer**: This is an unofficial CLI tool and is not affiliated with, endorsed by, or supported by Billingo.
 
 ## Features
 
-- Complete coverage of Billingo API v3 endpoints
-- Simple, intuitive command structure
-- JSON and pretty-print output formats
-- File-based and inline data input
-- Comprehensive error handling with rate limit management
-- Persistent configuration storage
-- Progress indicators for long-running operations
+- **Invoices** — Create, list, send, and manage invoices
+- **Partners** — Manage customers and suppliers
+- **Products** — Maintain product catalog
+- **Bank Accounts** — Manage payment accounts
+- **Organization** — View organization details and supported currencies
+- **JSON output** — All commands support `--json` for scripting
 
 ## Why CLI > MCP
 
-### The MCP Problem
+MCP servers are complex, stateful, and require a running server process. A CLI is:
 
-Model Context Protocol (MCP) servers introduce unnecessary complexity and failure points for API access:
-
-1. **Extra Infrastructure Layer**: MCP requires running a separate server process that sits between your AI agent and the API
-2. **Cognitive Overhead**: Agents must learn MCP-specific tool schemas on top of the actual API semantics
-3. **Debugging Nightmare**: When things fail, you're debugging three layers (AI → MCP → API) instead of two (AI → API)
-4. **Limited Flexibility**: MCP servers often implement a subset of API features, forcing you to extend or work around limitations
-5. **Maintenance Burden**: Every API change requires updating both the MCP server and documentation
-
-### The CLI Advantage
-
-A well-designed CLI is the superior abstraction for AI agents:
-
-1. **Zero Runtime Dependencies**: No server process to start, monitor, or crash
-2. **Direct API Access**: One hop from agent to API with transparent HTTP calls
-3. **Human + AI Usable**: Same tool works perfectly for both developers and agents
-4. **Self-Documenting**: Built-in `--help` text provides complete usage information
-5. **Composable**: Standard I/O allows piping, scripting, and integration with other tools
-6. **Better Errors**: Direct error messages from the API without translation layers
-7. **Instant Debugging**: `--format json` gives you the exact API response for inspection
-
-**Example Complexity Comparison:**
-
-MCP approach:
-```
-AI Agent → MCP Tool Schema → MCP Server → HTTP Request → API → Response Chain (reverse)
-```
-
-CLI approach:
-```
-AI Agent → Shell Command → HTTP Request → API → Direct Response
-```
-
-The CLI is simpler, faster, more reliable, and easier to debug.
+- **Simpler** — Just a binary you call directly
+- **Composable** — Pipe output to `jq`, `grep`, `awk`, and other tools
+- **Scriptable** — Use in shell scripts, CI/CD pipelines, cron jobs
+- **Debuggable** — See exactly what's happening with `--json` flag
+- **AI-friendly** — AI agents can call CLIs just as easily as MCPs, with less overhead
 
 ## Installation
 
 ```bash
-npm install -g @ktmcp-cli/billingo
-```
-
-Or install locally:
-
-```bash
-cd billingo
-npm install
-npm link
-```
-
-## Configuration
-
-### Set API Key
-
-Get your API key from https://app.billingo.hu/api-key
-
-```bash
-billingo config set apiKey YOUR_API_KEY_HERE
-```
-
-### Environment Variables
-
-Alternatively, use environment variables:
-
-```bash
-export BILLINGO_API_KEY=your_api_key_here
-export BILLINGO_BASE_URL=https://api.billingo.hu/v3  # Optional
+npm install -g @ktmcp-cli/billingohu
 ```
 
-### View Configuration
+## Authentication Setup
 
-```bash
-# Show all config
-billingo config list
-
-# Get specific value
-billingo config get apiKey
-
-# Clear all config
-billingo config clear
-```
-
-## Usage
-
-### General Syntax
+Configure your Billingo API key:
 
 ```bash
-billingo <resource> <action> [options]
+billingohu config set --api-key YOUR_API_KEY
 ```
 
-### Available Resources
-
-- `bank-accounts` (alias: `banks`) - Manage bank accounts
-- `documents` (alias: `docs`) - Manage invoices and documents
-- `document-blocks` (alias: `blocks`) - Manage invoice pads
-- `partners` - Manage customers and suppliers
-- `products` - Manage product catalog
-- `currencies` (alias: `currency`) - Currency conversion
-- `organization` (alias: `org`) - Organization information
-- `utils` - Utility functions
-
-### Global Options
-
-- `-f, --format <format>` - Output format: `json` or `pretty` (default: pretty)
-- `-h, --help` - Display help for command
-- `-v, --version` - Output version number
+Get your API key from [app.billingo.hu/api](https://app.billingo.hu/api)
 
-## Examples
+## Commands
 
-### Bank Accounts
+### Configuration
 
 ```bash
-# List all bank accounts
-billingo bank-accounts list
-
-# Get specific account
-billingo bank-accounts get 123
-
-# Create from JSON file
-billingo bank-accounts create --file account.json
-
-# Create from inline JSON
-billingo bank-accounts create --data '{"name":"Main Account","account_number":"12345678"}'
+# Set API key
+billingohu config set --api-key <key>
 
-# Update account
-billingo bank-accounts update 123 --file updated-account.json
-
-# Delete account
-billingo bank-accounts delete 123
+# Show current config
+billingohu config show
 ```
 
-### Documents (Invoices)
+### Invoices
 
 ```bash
-# List all documents
-billingo documents list --page 1 --per-page 25
-
-# Filter documents
-billingo documents list \
-  --partner-id 456 \
-  --payment-status paid \
-  --start-date 2024-01-01 \
-  --end-date 2024-12-31
-
-# Get specific document
-billingo documents get 789
-
-# Create document
-billingo documents create --file invoice.json
+# List invoices
+billingohu invoices list
+billingohu invoices list --type invoice --payment-method transfer
 
-# Cancel document
-billingo documents cancel 789
+# Get invoice details
+billingohu invoices get <invoice-id>
 
-# Download PDF
-billingo documents download 789 --output invoice-789.pdf
+# Create invoice
+billingohu invoices create --data '{...}'
 
-# Send via email
-billingo documents send 789 --emails "customer@example.com,accounting@example.com"
+# Send invoice via email
+billingohu invoices send <invoice-id> --emails "client@example.com"
 
-# Get public download URL
-billingo documents public-url 789
-
-# Get payment history
-billingo documents payments 789
-
-# Update payment history
-billingo documents update-payments 789 --file payments.json
-
-# Check Online Számla status
-billingo documents online-szamla 789
+# Delete invoice
+billingohu invoices delete <invoice-id>
 ```
 
-### Partners
+### Partners (Customers/Suppliers)
 
 ```bash
 # List partners
-billingo partners list
+billingohu partners list
 
-# Get partner
-billingo partners get 456
+# Get partner details
+billingohu partners get <partner-id>
 
 # Create partner
-billingo partners create --file partner.json
+billingohu partners create --data '{"name":"Acme Corp","email":"contact@acme.com"}'
 
 # Update partner
-billingo partners update 456 --data '{"name":"Updated Name"}'
+billingohu partners update <partner-id> --data '{...}'
 
 # Delete partner
-billingo partners delete 456
+billingohu partners delete <partner-id>
 ```
 
 ### Products
 
 ```bash
 # List products
-billingo products list
+billingohu products list
 
-# Get product
-billingo products get 321
+# Get product details
+billingohu products get <product-id>
 
 # Create product
-billingo products create --file product.json
+billingohu products create --data '{"name":"Service","net_unit_price":10000,"currency":"HUF"}'
 
 # Update product
-billingo products update 321 --file updated-product.json
+billingohu products update <product-id> --data '{...}'
 
 # Delete product
-billingo products delete 321
+billingohu products delete <product-id>
 ```
 
-### Currency Conversion
+### Bank Accounts
 
 ```bash
-# Get conversion rate
-billingo currencies convert --from HUF --to EUR
+# List bank accounts
+billingohu bank-accounts list
+
+# Get account details
+billingohu bank-accounts get <account-id>
 
-# Get rate in JSON format
-billingo currencies convert --from USD --to HUF --format json
+# Create bank account
+billingohu bank-accounts create --data '{...}'
 ```
 
 ### Organization
 
 ```bash
-# Get organization data
-billingo organization get
+# Show organization details
+billingohu organization show
 
-# JSON output
-billingo organization get --format json
+# List supported currencies
+billingohu organization currencies
 ```
 
-### Utilities
+## JSON Output
+
+All commands support `--json` for machine-readable output:
 
 ```bash
-# Convert legacy API ID to v3
-billingo utils convert-id 12345
-```
+# List invoices as JSON
+billingohu invoices list --json
 
-### Document Blocks
+# Pipe to jq for filtering
+billingohu invoices list --json | jq '.[] | select(.payment_status == "paid")'
 
-```bash
-# List invoice pads
-billingo document-blocks list
+# Get partner details
+billingohu partners get <id> --json
 ```
 
-## Data Formats
-
-### Creating a Document (Invoice)
+## Examples
 
-Example `invoice.json`:
+### Create invoice workflow
 
-```json
-{
-  "vendor_id": 1,
-  "partner_id": 123,
-  "block_id": 1,
+```bash
+# First, create a partner
+PARTNER_ID=$(billingohu partners create \
+  --data '{"name":"Acme Corp","email":"billing@acme.com","city":"Budapest"}' \
+  --json | jq -r '.id')
+
+# Create invoice
+billingohu invoices create --data '{
+  "partner_id": '$PARTNER_ID',
   "type": "invoice",
-  "fulfillment_date": "2024-01-15",
-  "due_date": "2024-01-30",
-  "payment_method": "transfer",
-  "language": "hu",
   "currency": "HUF",
   "items": [
     {
-      "name": "Web Development Service",
-      "unit_price": 50000,
-      "quantity": 10,
-      "unit": "hour",
-      "vat": "27%"
+      "name": "Consulting Services",
+      "net_unit_price": 100000,
+      "quantity": 1
     }
   ]
-}
-```
+}'
 
-### Creating a Partner
-
-Example `partner.json`:
-
-```json
-{
-  "name": "Example Company Ltd.",
-  "address": {
-    "country_code": "HU",
-    "post_code": "1234",
-    "city": "Budapest",
-    "address": "Example Street 42"
-  },
-  "emails": ["contact@example.com"],
-  "taxcode": "12345678-1-23"
-}
+# Send invoice
+billingohu invoices send <invoice-id> --emails "billing@acme.com"
 ```
 
-### Creating a Bank Account
-
-Example `account.json`:
-
-```json
-{
-  "name": "Main Business Account",
-  "account_number": "12345678-12345678",
-  "account_number_iban": "HU42123456781234567812345678",
-  "swift": "ABCDHUHB",
-  "currency": "HUF",
-  "need_qr": true
-}
-```
-
-## Error Handling
-
-The CLI provides clear error messages for common issues:
-
-- **401 Unauthorized** - Check your API key
-- **403 Forbidden** - Insufficient permissions
-- **404 Not Found** - Resource doesn't exist
-- **422 Validation Error** - Invalid data format
-- **429 Rate Limit** - Too many requests (shows retry time)
-- **500 Server Error** - Billingo API issue
-
-## Rate Limiting
-
-The API includes rate limit headers in responses:
-- `X-RateLimit-Limit` - Requests allowed per window
-- `X-RateLimit-Remaining` - Requests remaining
-- `X-RateLimit-Reset` - Reset timestamp
-
-The CLI warns you when fewer than 10 requests remain.
-
-## Development
+### List unpaid invoices
 
 ```bash
-# Install dependencies
-npm install
-
-# Run locally
-npm run dev -- documents list
-
-# Run directly
-node bin/billingo.js documents list
+billingohu invoices list --json | jq '.[] | select(.payment_status != "paid") | {id, invoice_number, partner_name, total_gross}'
 ```
 
-## API Documentation
-
-- Official API Docs: https://api.billingo.hu/v3/swagger
-- Support: https://support.billingo.hu/content/446136358
-- Generate API Key: https://app.billingo.hu/api-key
-
-## Supported Currencies
+## Contributing
 
-The API supports 37 currencies including:
-HUF, EUR, USD, GBP, CHF, AUD, CAD, DKK, NOK, SEK, CZK, PLN, RON, BGN, HRK, RSD, and more.
+Issues and pull requests are welcome at [github.com/ktmcp-cli/billingohu](https://github.com/ktmcp-cli/billingohu).
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE) for details.
 
-## Support
+---
 
-For issues and feature requests, please contact support or refer to the official Billingo documentation.
+Part of the [KTMCP CLI](https://killthemcp.com) project — replacing MCPs with simple, composable CLIs.

package/bin/billingo.js

@@ -1,75 +1,10 @@
 #!/usr/bin/env node
 
-/**
- * Billingo CLI - Main Entry Point
- *
- * Production-ready CLI for Billingo API v3
- * Hungarian invoicing and billing automation
- */
-
-import { Command } from 'commander';
-import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
-import chalk from 'chalk';
-
-// Import command modules
-import { registerBankAccountCommands } from '../src/commands/bank-accounts.js';
-import { registerDocumentCommands } from '../src/commands/documents.js';
-import { registerDocumentBlockCommands } from '../src/commands/document-blocks.js';
-import { registerPartnerCommands } from '../src/commands/partners.js';
-import { registerProductCommands } from '../src/commands/products.js';
-import { registerCurrencyCommands } from '../src/commands/currencies.js';
-import { registerOrganizationCommands } from '../src/commands/organization.js';
-import { registerUtilityCommands } from '../src/commands/utilities.js';
-import { registerConfigCommands } from '../src/commands/config.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// Load package.json
-const packageJson = JSON.parse(
-  readFileSync(join(__dirname, '../package.json'), 'utf-8')
-);
-
-const program = new Command();
-
-// Configure main program
-program
-  .name('billingo')
-  .description(chalk.cyan('Billingo API v3 CLI - Hungarian invoicing and billing automation'))
-  .version(packageJson.version, '-v, --version', 'output the current version')
-  .addHelpText('after', `
-${chalk.bold('Examples:')}
-  $ billingo config set API_KEY <your-api-key>
-  $ billingo documents list --page 1 --per-page 25
-  $ billingo documents create -f invoice.json
-  $ billingo partners list
-  $ billingo bank-accounts list
-
-${chalk.bold('API Documentation:')}
-  ${chalk.blue('https://api.billingo.hu/v3/swagger')}
-
-${chalk.bold('Get API Key:')}
-  ${chalk.blue('https://app.billingo.hu/api-key')}
-`);
-
-// Register all command modules
-registerConfigCommands(program);
-registerBankAccountCommands(program);
-registerDocumentCommands(program);
-registerDocumentBlockCommands(program);
-registerPartnerCommands(program);
-registerProductCommands(program);
-registerCurrencyCommands(program);
-registerOrganizationCommands(program);
-registerUtilityCommands(program);
-
-// Global error handler
-process.on('unhandledRejection', (error) => {
-  console.error(chalk.red('Unhandled error:'), error);
-  process.exit(1);
-});
-
-// Parse command line arguments
-program.parse(process.argv);
+// Import and run the main CLI
+import(join(__dirname, '..', 'src', 'index.js'));

package/package.json

@@ -1,23 +1,19 @@
 {
   "name": "@ktmcp-cli/billingo",
-  "version": "1.0.0",
-  "description": "Production-ready CLI for Billingo API v3 - Hungarian invoicing and billing",
+  "version": "1.0.1",
+  "description": "Production-ready CLI for Billingo API v3 - invoicing, billing, partners",
   "type": "module",
   "main": "src/index.js",
   "bin": {
-    "billingo": "./bin/billingo.js"
-  },
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "dev": "node bin/billingo.js"
+    "billingo": "bin/billingo.js"
   },
   "keywords": [
     "billingo",
-    "invoice",
+    "invoicing",
     "billing",
-    "hungary",
     "cli",
-    "api"
+    "api",
+    "ktmcp"
   ],
   "author": "KTMCP",
   "license": "MIT",
@@ -31,5 +27,13 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ktmcp-cli/billingo.git"
+  },
+  "homepage": "https://killthemcp.com/billingo-cli",
+  "bugs": {
+    "url": "https://github.com/ktmcp-cli/billingo/issues"
   }
 }