KolShek CLI Documentation

Complete reference for every command, flag, and integration in KolShek.

Global Options

All commands support these flags:

init

First-run setup wizard — configure your first provider.

kolshek init

providers

Manage bank and credit card providers.

providers list

List configured providers.

providers add

Add a new bank or credit card provider.

providers auth <id>

Set or update credentials for an existing provider.

providers remove <id>

Remove a configured provider.

providers test <id>

Test provider credentials.

fetch [providers...]

Fetch transactions from all or specific providers.

kolshek fetch                    # all providers
kolshek fetch leumi visa-cal     # specific providers
kolshek fetch --from 30d         # last 30 days

accounts alias: bal

Show accounts and balances.

transactions alias: tx

List, search, and export transactions.

transactions list

List transactions with filters.

transactions search <query>

Search transactions by description.

transactions delete <id>

Delete a transaction by ID. Use only for duplicates or erroneous records.

transactions export <format>

Export transactions to CSV or JSON.

db

Inspect database schema (tables and columns).

db tables

List available tables.

db schema <table>

Show column details for a table.

query <sql> alias: sql

Run a read-only SQL query. Supports SELECT, WITH, EXPLAIN, PRAGMA, and VALUES.

kolshek query "SELECT * FROM transactions ORDER BY date DESC LIMIT 10"
kolshek sql "SELECT category, SUM(chargedAmount) FROM transactions GROUP BY category"

reports alias: report

Financial analysis reports.

reports monthly

Monthly income/expenses/net breakdown.

reports categories

Expense breakdown by category.

reports merchants

Top merchants by spend.

reports balance

Account balances with 30-day activity summary.

categorize alias: cat

Manage category rules and apply them to transactions.

categorize rule add <category>

Create a category rule.

categorize rule list

List all category rules.

categorize rule remove <id>

Delete a category rule.

categorize rule import [file]

Bulk-import category rules from JSON file or stdin.

categorize apply

Run category rules on transactions.

categorize rename <old> <new>

Rename or merge a category (updates transactions and rules).

categorize migrate

Bulk rename/merge categories from a JSON mapping file.

categorize reassign

Force-reassign transactions matching a pattern to a new category.

categorize list

Show categories with transaction counts, totals, and source.

translate alias: tr

Manage Hebrew-to-English translation rules for transaction descriptions.

translate rule add <english>

Create a translation rule.

translate rule list

List all translation rules.

translate rule remove <id>

Delete a translation rule.

translate rule import [file]

Bulk-import translation rules from JSON file or stdin.

translate apply

Run translation rules on transactions with NULL description_en.

schedule

Manage automatic fetch scheduling.

schedule set

Register a recurring fetch task with the OS scheduler.

schedule remove

Unregister the recurring fetch task.

schedule status

Show current schedule status.

plugin

Manage AI agent integrations.

plugin install <tool>

Install AI plugin for a tool.

kolshek plugin install claude-code
kolshek plugin install cursor
kolshek plugin install gemini-cli

Supported tools: claude-code, openclaw, cursor, gemini-cli, antigravity, opencode, aider, windsurf.

plugin list

List available tool integrations.

spending [month]

Spending breakdown by category, merchant, or provider.

kolshek spending              # current month
kolshek spending 2026-01      # specific month
kolshek spending -m 3         # 3 months ago

spending exclude add <category>

Mark a category as non-spending.

spending exclude remove <category>

Remove a category from the exclusion list.

spending exclude list

Show all excluded categories.

income [month]

Income breakdown with salary detection (bank accounts only by default).

trends [months]

Multi-month cashflow and spending trend analysis. Default: 6 months.

insights

Financial alerts and recommendations based on spending patterns.

update

Self-update KolShek to the latest release. Downloads the correct binary for your platform from GitHub and replaces the current executable in-place.

Security Model

KolShek handles real bank credentials. Security is not optional.

Credential Storage

Credentials are stored using a layered strategy:

1. Environment variables (CI/automation) — checked first via KOLSHEK_CREDENTIALS_JSON
2. OS keychain (primary) — Windows Credential Manager, macOS Keychain, or Linux secret-tool
3. Encrypted file (fallback) — AES-256-GCM encrypted local file when no keychain is available

Credentials are never logged, never included in error messages, and zeroed from memory after use.

File Permissions

Database and config files are restricted to owner-only access:

• Windows: icacls removes inherited permissions, grants full control only to the current user
• Unix: chmod 600 for files, chmod 700 for directories

Read-Only Query Command

The kolshek query command enforces read-only access:

• Only SELECT, WITH, EXPLAIN, PRAGMA, and VALUES are allowed
• INSERT, UPDATE, DELETE, DROP, ALTER, CREATE are blocked
• PRAGMA restricted to a whitelist of read-only pragmas
• Table names in db schema validated against [a-z_]+

Web Dashboard Security

• Localhost only — Bun.serve() binds to hostname: "localhost"
• CSRF protection — Origin header checked on all non-GET/HEAD requests
• Security headers — X-Content-Type-Options: nosniff and X-Frame-Options: DENY
• XSS prevention — all user-controlled content is HTML-escaped
• Parameterized SQL — all operations use prepared statements

Dependency Pinning

Critical dependencies are pinned to exact versions to prevent supply-chain attacks. israeli-bank-scrapers-core is pinned to 6.7.1 (no caret).

AI Agent Integration

KolShek is built for AI agents. Every command supports --json for structured output, and the query and db commands give agents direct SQL access.

Install a Plugin

kolshek plugin install claude-code
kolshek plugin install cursor
kolshek plugin install gemini-cli

Run kolshek plugin list to see all available integrations.

Structured Output

Every command supports --json, returning a consistent envelope:

{
  "success": true,
  "data": { ... },
  "metadata": { "count": 42, "from": "2026-01-01", "to": "2026-03-16" }
}

Errors follow the same pattern:

{
  "success": false,
  "error": {
    "code": "AUTH_FAILED",
    "message": "Authentication failed for provider hapoalim",
    "retryable": false,
    "suggestions": ["Run 'kolshek providers test hapoalim'"]
  }
}

Schema Discovery

Agents can discover the database schema without prior knowledge:

kolshek db tables --json
kolshek db schema transactions --json

Exit Codes

Non-Interactive Mode

kolshek fetch --non-interactive --json

If input is required (e.g., OTP), the command fails with exit code 3 instead of hanging.

Web Dashboard

Browser UI for managing providers, categories, and translations.

Quick Start

kolshek dashboard

Opens a local web server (default: http://localhost:5556) with three pages:

• Providers — add, edit, remove, and test bank/credit card connections; fetch with real-time progress
• Categories — create category rules, view spending breakdowns, reassign transactions
• Translations — manage Hebrew-to-English merchant name mappings

Provider Management

• Add providers by selecting a bank/credit card and entering credentials
• Test connections before saving
• Fetch transactions with real-time SSE progress

Category Rules

• Match on description, memo, amount, account, or direction
• Substring, exact, and regex matching
• Priority-based rule evaluation
• Apply to uncategorized or re-apply to all

Translation Rules

• Map Hebrew merchant names to English
• View untranslated descriptions grouped by frequency
• One-click rule creation from untranslated list

Architecture

Built with Bun.serve() (localhost-only HTTP server), HTMX (dynamic updates without a JS framework), Tailwind CSS v4, and SSE for real-time fetch progress. All data stays local.