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.

Changelog

v0.3.7

Features

• Full React dashboard — migrated from HTMX to a full React SPA with client-side routing. 8 pages: Dashboard, Transactions, Spending, Trends, Insights, Categories, Translations, Providers.
• Per-provider sync events — SSE now emits granular events per provider during sync, enabling real-time progress tracking in the dashboard.
• Cross-origin authentication — dashboard auth now works across origins, supporting the desktop app sidecar architecture.
• Dashboard analytics — net worth card, cashflow chart, spending donut, automated insights, and recent transactions view.
• Landing page polish — GitHub stars badge, trimmed favicon, theme toggle simplification, docs sidebar reorder, chat auto-scroll.

v0.3.6

Features

• Multi-agent plugin rewrite — consolidated plugin system from 7+ tool-specific integration folders into a single canonical source. Skills now install from one source to Claude Code, OpenCode, Codex, and OpenClaw.
• New skills — analyze and review — /kolshek:analyze for deep-dive financial analysis with budget targets, and /kolshek:review for monthly spending reviews with progress report cards.
• CLI reference documentation — added complete CLI reference to plugin skills covering all commands, global flags, command aliases, exit codes, DB schema, and SQL patterns.

Bug Fixes

• Fixed init wizard offering unsupported AI tools (removed Cursor, Gemini CLI, Windsurf, Aider; added OpenCode, Codex)
• Fixed Codex skill install path — now installs to ~/.codex/skills/
• Fixed OpenClaw skill install path — now installs to ~/.openclaw/workspace/skills/
• Fixed --type flag documentation — corrected to --type <bank|credit_card>
• Removed dead /kolshek:budget-app references
• Fixed /dev/null usage in check-config hook for Windows compatibility

Other

• Standardized skill frontmatter with consistent allowed-tools, compatibility, and metadata fields
• Added missing commands to CLI reference (dashboard, update, plugin)
• Added release step for plugin bundle regeneration

v0.3.5

Security

• Migrated credential storage to Bun.secrets — replaces platform-specific subprocess wrappers with Bun’s native API. Eliminates credential exposure in process listings.
• Input validation on credential aliases — validates against prototype pollution, path traversal, and special character injection.
• Atomic credential file writes — write-to-temp + rename to prevent corruption on crash.
• Windows permission hardening — credential files now get explicit owner-only ACLs via icacls.
• Keychain probe caching — avoids repeated probe writes that could leave residual entries.
• Payload size limits — credential payloads larger than 64KB are rejected.
• Security test suite — 47 unit tests covering alias validation, AES-256-GCM roundtrips, tamper detection, and more.

v0.3.4

Features

• Self-update command — new kolshek update downloads and installs the latest release binary from GitHub. Use --check to check without installing.

v0.3.3

Bug Fixes

• macOS keychain credentials not readable after save — fixed providers add saving credentials that couldn’t be read back on macOS.

Other

• Landing site switched from GitHub Pages to Cloudflare Pages
• Added BETA badge, live download counter, docs page, provider logos, and plugin picker

v0.3.2

Features

• Web settings dashboard — new kolshek dashboard launches an HTMX-powered browser UI for managing providers, categories, and translations with real-time SSE progress.
• Custom Tailwind v4 design system — dashboard uses a custom indigo/zinc design system with dark mode.
• Logo — KolShek logo added to dashboard navbar and favicon.

Security

• Localhost-only binding, CSRF protection, XSS prevention, security headers
• Type-safe rule validation and server-side alias validation

Other

• Added MIT license, security policy, and documentation site
• Extracted shared utilities, wrapped translation rules in DB transaction

v0.3.1

Features

• Lifestyle spending mode — new spending --lifestyle flag excludes financial mechanics from spending reports.
• Duplicate rule detection — categorize rule add blocks duplicate conditions.

Bug Fixes

• Mutating PRAGMAs bypassed query validation
• LIMIT appended to PRAGMA/VALUES queries causing syntax errors
• Insights included excluded categories

v0.3.0

Features

• Spending command — spending [month] with grouping by category, merchant, or provider.
• Income command — income [month] with salary detection and transfer classification.
• Trends command — month-over-month spending and income trends.
• Insights command — automated financial alerts for category spikes, large transactions, new merchants, and more.

Bug Fixes

• Fixed broken merchant insights (snake_case/camelCase mapping)
• Fixed wrong merchant average calculation (per-month vs per-transaction)
• Fixed missing transfer classification in income
• Fixed silent invalid month fallback in spending/income
• Fixed insights NaN crash on invalid --months

v0.2.0

Features

• Multi-field category rule engine — match on multiple fields with AND logic, regex/substring/exact modes, and priority ordering.
• Recategorize and reassign commands — re-apply updated rules to existing transactions.
• Category bulk import, migration, and rename
• CC billing charge handling — detect and flag credit card billing lines to prevent double-counting.

Security

• Windows file permission hardening via icacls
• Credential zeroing after use
• Read-only PRAGMA whitelist, SQL injection guard on schema introspection
• Pinned scraper dependency to exact version