@ktmcp-cli/nordigen 1.0.0 → 1.0.2

package/README.md

@@ -1,424 +1,236 @@
-# Nordigen CLI
+> "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/)
 
-<p align="center">
-  <img src="banner.png" alt="KTMCP Banner" width="100%">
-</p>
+# Nordigen CLI
 
+A production-ready command-line interface for the [Nordigen](https://nordigen.com) Account Information Services API. Access bank account data, transactions, balances, and manage open banking connections directly from your terminal.
 
-Production-ready command-line interface for the Nordigen Account Information Services API (Open Banking).
+> **Disclaimer**: This is an unofficial CLI tool and is not affiliated with, endorsed by, or supported by Nordigen or GoCardless.
 
 ## Features
 
-- Complete coverage of Nordigen API v2
-- JWT authentication with automatic token refresh
-- Secure credential storage
-- Rich terminal output with colors and formatting
-- JSON output for scripting and automation
-- Comprehensive error handling
-- Support for all major operations:
-  - Account information (balances, details, transactions)
-  - Institution browsing and search
-  - End User Agreements (EUA) management
-  - Requisition creation and management
-  - Payment operations
+- **Institutions** — Browse and search banks across 31 European countries
+- **Agreements** — Create and manage end user agreements for account access
+- **Requisitions** — Initiate bank connections and retrieve authorization links
+- **Accounts** — Access account metadata, balances, details, and transactions
+- **JWT Authentication** — Secure authentication with automatic token refresh
+- **JSON output** — All commands support `--json` for scripting and piping
+- **Colorized output** — Clean, readable terminal output with chalk
 
-## Installation
+## Why CLI > MCP
 
-### From Source
+MCP servers are complex, stateful, and require a running server process. A CLI is:
 
-```bash
-cd /workspace/group/ktmcp/workspace/nordigen
-npm install
-chmod +x bin/nordigen.js
-npm link  # or add to PATH
-```
+- **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
 
-### From NPM (when published)
+## Installation
 
 ```bash
-npm install -g @ktmcp-cli/nordigen
+npm install -g @ktmcp-cli/nordigencom
 ```
 
-## Quick Start
+## Authentication Setup
 
-### 1. Authentication
+Nordigen uses JWT authentication. You'll need to create a Nordigen account and obtain API credentials.
 
-First, obtain your API credentials from the Nordigen dashboard at https://nordigen.com
+### 1. Create a Nordigen Account
 
-```bash
-# Login with your credentials
-nordigen auth login --secret-id YOUR_SECRET_ID --secret-key YOUR_SECRET_KEY
-
-# Check authentication status
-nordigen auth status
-```
+1. Go to [nordigen.com](https://nordigen.com) or [ob.nordigen.com/account/login/](https://ob.nordigen.com/account/login/)
+2. Sign up for a free or paid account
+3. Navigate to **User Secrets** in the dashboard
+4. Copy your **Secret ID** and **Secret Key**
 
-### 2. Browse Institutions
+### 2. Configure the CLI
 
 ```bash
-# List banks in Great Britain
-nordigen institutions list --country GB
-
-# Search for a specific bank
-nordigen institutions search "Barclays" --country GB
-
-# Get details for a specific institution
-nordigen institutions get BARCLAYS_BARCGB22
+nordigencom config set --secret-id YOUR_SECRET_ID --secret-key YOUR_SECRET_KEY
 ```
 
-### 3. Create End User Agreement
+### 3. Login
 
 ```bash
-# Create an agreement for accessing account data
-nordigen agreements create \
-  --institution-id BARCLAYS_BARCGB22 \
-  --max-days 90 \
-  --valid-days 90
+nordigencom auth login
 ```
 
-### 4. Create Requisition
+This will obtain a JWT access token that's valid for 24 hours and automatically refresh it when needed.
 
-```bash
-# Create a requisition to connect a bank account
-nordigen requisitions create \
-  --institution-id BARCLAYS_BARCGB22 \
-  --redirect https://yourapp.com/callback \
-  --agreement <AGREEMENT_ID>
+### 4. Verify
 
-# The command will return an authentication link
-# Send this link to the end user to authorize access
+```bash
+nordigencom auth status
 ```
 
-### 5. Access Account Data
-
-```bash
-# Get account metadata
-nordigen accounts get <ACCOUNT_ID>
+## Commands
 
-# Get account balances
-nordigen accounts balances <ACCOUNT_ID>
+### Configuration
 
-# Get account transactions
-nordigen accounts transactions <ACCOUNT_ID>
+```bash
+# Set credentials
+nordigencom config set --secret-id <id> --secret-key <key>
 
-# Get transactions for a date range
-nordigen accounts transactions <ACCOUNT_ID> \
-  --from 2024-01-01 \
-  --to 2024-12-31
+# Show current config
+nordigencom config show
 ```
 
-## Command Reference
-
 ### Authentication
 
 ```bash
-# Login
-nordigen auth login --secret-id <id> --secret-key <key>
-
-# Check status
-nordigen auth status
+# Login and obtain JWT token
+nordigencom auth login
 
-# Logout
-nordigen auth logout
+# Check auth status
+nordigencom auth status
 ```
 
 ### Institutions
 
 ```bash
-# List institutions
-nordigen institutions list --country <CODE>
-nordigen institutions list --country GB --payments
+# List all institutions
+nordigencom institutions list
 
-# Search institutions
-nordigen institutions search <query> --country <CODE>
+# Filter by country
+nordigencom institutions list --country GB
+nordigencom institutions list --country DE
 
 # Get institution details
-nordigen institutions get <INSTITUTION_ID>
+nordigencom institutions get <institution-id>
 ```
 
-### End User Agreements
+### Agreements
+
+End user agreements define what data you can access and for how long.
 
 ```bash
-# List agreements
-nordigen agreements list
+# List all agreements
+nordigencom agreements list
 
-# Create agreement
-nordigen agreements create \
-  --institution-id <ID> \
-  --max-days 90 \
-  --valid-days 90 \
-  --scope balances details transactions
+# Get specific agreement
+nordigencom agreements get <agreement-id>
 
-# Get agreement
-nordigen agreements get <AGREEMENT_ID>
+# Create new agreement
+nordigencom agreements create \
+  --institution-id <institution-id> \
+  --max-historical-days 90 \
+  --access-valid-for-days 90
 
-# Delete agreement
-nordigen agreements delete <AGREEMENT_ID> --yes
+# Create agreement with limited scope
+nordigencom agreements create \
+  --institution-id <institution-id> \
+  --access-scope balances,transactions
 
-# Accept agreement (programmatically)
-nordigen agreements accept <AGREEMENT_ID> \
-  --user-agent "Mozilla/5.0..." \
-  --ip "192.168.1.1"
+# Delete agreement
+nordigencom agreements delete <agreement-id>
 ```
 
 ### Requisitions
 
+Requisitions are bank connection requests that users authorize.
+
 ```bash
-# List requisitions
-nordigen requisitions list
+# List all requisitions
+nordigencom requisitions list
 
-# Create requisition
-nordigen requisitions create \
-  --institution-id <ID> \
-  --redirect <URL> \
-  --reference "my-ref" \
-  --agreement <AGREEMENT_ID>
+# Get specific requisition
+nordigencom requisitions get <requisition-id>
 
-# Get requisition
-nordigen requisitions get <REQUISITION_ID>
+# Create new requisition
+nordigencom requisitions create \
+  --institution-id <institution-id> \
+  --redirect https://yourapp.com/callback \
+  --reference user-123 \
+  --agreement-id <agreement-id>
 
 # Delete requisition
-nordigen requisitions delete <REQUISITION_ID> --yes
+nordigencom requisitions delete <requisition-id>
 ```
 
 ### Accounts
 
+Access account data after a requisition is authorized.
+
 ```bash
 # Get account metadata
-nordigen accounts get <ACCOUNT_ID>
+nordigencom accounts get <account-id>
 
-# Get balances
-nordigen accounts balances <ACCOUNT_ID>
+# Get account balances
+nordigencom accounts balances <account-id>
 
 # Get account details
-nordigen accounts details <ACCOUNT_ID>
-
-# Get transactions
-nordigen accounts transactions <ACCOUNT_ID>
-nordigen accounts transactions <ACCOUNT_ID> --from 2024-01-01 --to 2024-12-31
-
-# Premium transactions (with country-specific data)
-nordigen accounts transactions <ACCOUNT_ID> --premium --country GB
-```
-
-### Payments
-
-```bash
-# List payments
-nordigen payments list
-
-# Get payment details
-nordigen payments get <PAYMENT_ID>
-
-# Delete payment
-nordigen payments delete <PAYMENT_ID> --yes
-
-# List creditors
-nordigen payments creditors
-
-# Get required payment fields for institution
-nordigen payments fields <INSTITUTION_ID>
-```
-
-### Configuration
-
-```bash
-# Show configuration
-nordigen config show
-nordigen config show --show-secrets  # WARNING: displays sensitive data
-
-# Get specific value
-nordigen config get auth.secret_id
+nordigencom accounts details <account-id>
 
-# Set value
-nordigen config set defaults.country GB
-
-# Set default country
-nordigen config set-country GB
-
-# Clear all configuration
-nordigen config clear --yes
+# Get account transactions
+nordigencom accounts transactions <account-id>
 ```
 
 ## JSON Output
 
-All commands support `--json` or `-j` flag for machine-readable output:
+All commands support `--json` for machine-readable output:
 
 ```bash
-# Get account as JSON
-nordigen accounts get <ACCOUNT_ID> --json
-
-# Pipe to jq for processing
-nordigen institutions list --country GB --json | jq '.[].name'
-```
-
-## Environment Variables
-
-- `DEBUG=1` - Enable debug output with stack traces
-- `NORDIGEN_SECRET_ID` - Alternative to storing secret ID in config
-- `NORDIGEN_SECRET_KEY` - Alternative to storing secret key in config
-
-## Configuration Storage
-
-Configuration is stored securely in:
-
-- **Linux/macOS**: `~/.config/nordigen-cli/config.json`
-- **Windows**: `%APPDATA%\nordigen-cli\config.json`
-
-The config file has permissions set to `0600` (read/write for owner only).
-
-## Error Handling
+# Get all institutions as JSON
+nordigencom institutions list --json
 
-The CLI provides detailed error messages with exit codes:
+# Pipe to jq for filtering
+nordigencom institutions list --country GB --json | jq '.[] | {id, name, bic}'
 
-- `0` - Success
-- `1` - General error
-- `400` - Bad request / validation error
-- `401` - Authentication error
-- `403` - Permission denied
-- `404` - Resource not found
-- `429` - Rate limit exceeded
-- `500` - Server error
-
-Enable debug output for detailed stack traces:
-
-```bash
-DEBUG=1 nordigen accounts get <ACCOUNT_ID>
+# Get transactions as JSON
+nordigencom accounts transactions <account-id> --json
 ```
 
-## Common Workflows
+## Examples
 
-### Complete Bank Connection Flow
+### Connect a bank account (full workflow)
 
 ```bash
-# 1. Find the institution
-nordigen institutions search "Your Bank" --country GB
+# Step 1: Find the bank institution
+nordigencom institutions list --country GB
+# Note the institution_id
 
-# 2. Create end user agreement
-nordigen agreements create --institution-id <INST_ID> --max-days 90
+# Step 2: Create an agreement
+nordigencom agreements create \
+  --institution-id SANDBOXFINANCE_SFIN0000 \
+  --max-historical-days 90 \
+  --access-valid-for-days 90
+# Note the agreement_id
 
-# 3. Create requisition
-nordigen requisitions create \
-  --institution-id <INST_ID> \
-  --redirect https://yourapp.com/callback \
-  --agreement <AGREEMENT_ID>
-
-# 4. Send the returned link to your user for authentication
+# Step 3: Create a requisition
+nordigencom requisitions create \
+  --institution-id SANDBOXFINANCE_SFIN0000 \
+  --redirect https://myapp.com/callback \
+  --reference user-123 \
+  --agreement-id <agreement-id>
+# Note the link URL and send it to the user
 
-# 5. After user authenticates, retrieve accounts
-nordigen requisitions get <REQUISITION_ID>
+# Step 4: After user authorizes, get the requisition
+nordigencom requisitions get <requisition-id>
+# Note the account IDs in the response
 
-# 6. Access account data
-nordigen accounts balances <ACCOUNT_ID>
-nordigen accounts transactions <ACCOUNT_ID>
+# Step 5: Access account data
+nordigencom accounts balances <account-id>
+nordigencom accounts transactions <account-id>
 ```
 
-### Batch Processing Accounts
+### Monitor account transactions
 
 ```bash
-# Get all requisitions as JSON
-nordigen requisitions list --json > requisitions.json
-
-# Extract account IDs and fetch transactions
-cat requisitions.json | jq -r '.results[].accounts[]' | while read account; do
-  echo "Fetching transactions for $account"
-  nordigen accounts transactions $account --json > "transactions_${account}.json"
-done
+# Get all transactions for an account
+nordigencom accounts transactions <account-id> --json | jq '.transactions.booked[] | {date: .bookingDate, amount: .transactionAmount.amount, description: .remittanceInformationUnstructured}'
 ```
 
-## Why CLI > MCP?
-
-### Performance
-- **CLI**: Direct execution, no protocol overhead, instant responses
-- **MCP**: Additional network/IPC layer, serialization overhead, slower responses
-
-### Simplicity
-- **CLI**: Simple command invocation, standard UNIX patterns, easy to compose
-- **MCP**: Requires server setup, protocol understanding, more moving parts
-
-### Debugging
-- **CLI**: Standard stdout/stderr, easy to debug with DEBUG flag
-- **MCP**: Protocol messages, requires MCP-specific debugging tools
-
-### Integration
-- **CLI**: Works with any language via subprocess, easy shell scripting
-- **MCP**: Requires MCP client library, limited language support
-
-### Portability
-- **CLI**: Single binary/script, runs anywhere with Node.js
-- **MCP**: Requires MCP server runtime, more dependencies
-
-### Use Cases
+## Contributing
 
-**Use CLI when:**
-- Building scripts and automation
-- One-off data retrieval tasks
-- Integrating with existing shell workflows
-- Debugging API responses
-- Human interaction needed
-
-**Use MCP when:**
-- Building persistent AI agent applications
-- Need stateful server connections
-- Multiple AI tools need shared context
-- Protocol-level features required
-
-## Troubleshooting
-
-### Token Expired
-
-```bash
-# Check authentication status
-nordigen auth status
-
-# Re-login if needed
-nordigen auth login --secret-id <id> --secret-key <key>
-```
-
-### Rate Limiting
-
-If you hit rate limits, the API will return a 429 error. Wait and retry, or implement exponential backoff in your scripts.
-
-### Account Access Errors
-
-Ensure:
-1. Valid End User Agreement exists
-2. Agreement has correct access scope
-3. User has completed authentication flow
-4. Access period hasn't expired
-
-## API Documentation
-
-For complete API reference, see:
-- Official Nordigen Docs: https://nordigen.com/en/docs/
-- OpenAPI Spec: https://ob.nordigen.com/api/swagger/
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Lint code
-npm run lint
-
-# Make executable
-chmod +x bin/nordigen.js
-```
+Issues and pull requests are welcome at [github.com/ktmcp-cli/nordigencom](https://github.com/ktmcp-cli/nordigencom).
 
 ## License
 
-MIT
-
-## Support
-
-- GitHub Issues: https://github.com/ktmcp/nordigen-cli/issues
-- Email: support@ktmcp.com
+MIT — see [LICENSE](LICENSE) for details.
 
-## Related Documentation
+---
 
-- [AGENT.md](./AGENT.md) - AI agent integration patterns
-- [OPENCLAW.md](./OPENCLAW.md) - OpenClaw integration guide
+Part of the [KTMCP CLI](https://killthemcp.com) project — replacing MCPs with simple, composable CLIs.

package/bin/nordigen.js

@@ -1,84 +1,10 @@
 #!/usr/bin/env node
 
-/**
- * Nordigen CLI - Production-ready command-line interface for Nordigen API
- *
- * @fileoverview Main entry point for the Nordigen CLI application
- * @module nordigen-cli
- */
-
-import { Command } from 'commander';
-import chalk from 'chalk';
-import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 
-// Import commands
-import { authCommand } from '../src/commands/auth.js';
-import { accountsCommand } from '../src/commands/accounts.js';
-import { institutionsCommand } from '../src/commands/institutions.js';
-import { agreementsCommand } from '../src/commands/agreements.js';
-import { requisitionsCommand } from '../src/commands/requisitions.js';
-import { paymentsCommand } from '../src/commands/payments.js';
-import { configCommand } from '../src/commands/config.js';
-
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
-
-const program = new Command();
-
-program
-  .name('nordigen')
-  .description('Production-ready CLI for Nordigen Open Banking API')
-  .version(packageJson.version)
-  .addHelpText('after', `
-${chalk.bold('Examples:')}
-  ${chalk.cyan('$ nordigen auth login --secret-id <id> --secret-key <key>')}
-  ${chalk.cyan('$ nordigen institutions list --country GB')}
-  ${chalk.cyan('$ nordigen accounts list')}
-  ${chalk.cyan('$ nordigen accounts transactions <account-id>')}
-
-${chalk.bold('Documentation:')}
-  README.md    - Complete usage guide
-  AGENT.md     - AI agent integration patterns
-  OPENCLAW.md  - OpenClaw integration guide
-
-${chalk.bold('Support:')}
-  GitHub: https://github.com/ktmcp/nordigen-cli
-  API Docs: https://nordigen.com/en/docs/
-`);
-
-// Register all commands
-program.addCommand(authCommand);
-program.addCommand(accountsCommand);
-program.addCommand(institutionsCommand);
-program.addCommand(agreementsCommand);
-program.addCommand(requisitionsCommand);
-program.addCommand(paymentsCommand);
-program.addCommand(configCommand);
-
-// Global error handling
-process.on('unhandledRejection', (error) => {
-  console.error(chalk.red('Error:'), error.message);
-  if (process.env.DEBUG) {
-    console.error(error.stack);
-  }
-  process.exit(1);
-});
-
-process.on('uncaughtException', (error) => {
-  console.error(chalk.red('Fatal Error:'), error.message);
-  if (process.env.DEBUG) {
-    console.error(error.stack);
-  }
-  process.exit(1);
-});
-
-// Parse arguments
-program.parse(process.argv);
 
-// Show help if no arguments provided
-if (!process.argv.slice(2).length) {
-  program.outputHelp();
-}
+// Import and run the main CLI
+import(join(__dirname, '..', 'src', 'index.js'));