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.

categorize classify set <category> <classification>

Set the classification for a category.

categorize classify list

Show all categories with their classifications.

categorize classify auto

Auto-classify categories based on dominant transaction direction.

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 opencode
kolshek plugin install codex
kolshek plugin install openclaw

Supported tools: claude-code, opencode, codex, openclaw.

plugin list

List available tool integrations.

dashboard

Open the settings dashboard in your browser.

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

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.

uninstall

Remove KolShek from this machine.

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 opencode
kolshek plugin install codex
kolshek plugin install openclaw

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:45091) with a React SPA dashboard featuring 8 pages:

• Dashboard — net worth overview, cashflow chart, spending breakdown, automated insights, recent transactions
• Transactions — browse, search, and filter all transactions with pagination
• Spending — monthly spending breakdown by category, merchant, or provider
• Trends — multi-month cashflow and spending trend analysis with charts
• Insights — financial alerts and recommendations based on spending patterns
• Categories — create category rules, view spending breakdowns, manage classifications
• Translations — manage Hebrew-to-English merchant name mappings
• Providers — add, edit, remove, and test connections; fetch with real-time sync progress

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), React (full SPA with client-side routing), Tailwind CSS v4 with Recharts for data visualization, and SSE for real-time per-provider sync progress. All data stays local.

Changelog

v0.4.0

Features

• AI chat agent — Talk to your financial data in the dashboard using a local LLM. Download and run GGUF models (Qwen, Gemma, Llama) with Vulkan/CUDA/CPU auto-detection — no cloud API keys required. The agent can query your database, run CLI commands, search transactions, analyze spending, and load domain-specific skills, all with real-time streaming, markdown rendering, and tool call visualization.
• AI model management — Download, switch, and configure models from the dashboard. Tier-based inference profiles automatically scale context window, available tools, and iteration limits to match model capability. Toggle thinking mode and resize context per-session.
• Sync cancellation — Cancel in-progress bank syncs from the dashboard.
• Category rules from transactions — Create categorization rules directly from individual transactions.
• Translation pagination — Server-side pagination for translation rule lists.
• Currency normalization — Automatically normalize currency symbols to ISO 4217 codes during sync.

Bug Fixes

• Aborted stream handling — Properly handle aborted SSE streams and filter empty assistant messages that caused the LLM to loop on tool calls.
• Stale chat history — Fixed race condition where rapid messages during active streaming would send incomplete conversation history to the model.

Security

• SQL injection hardening — Block write keywords (INSERT, UPDATE, DELETE, DROP, etc.) even inside CTEs that bypass the read-only prefix check. Secondary defense via columnNames check retained.
• Subprocess credential isolation — Subprocess environment uses a denylist to strip secrets (API keys, tokens, passwords, cloud credentials) while keeping system vars needed for module resolution.
• Subprocess timeout — CLI commands spawned by the agent are killed after 60 seconds to prevent hung processes from blocking inference indefinitely.
• Inference concurrency lock — Prevents concurrent access to the shared LLM sequence/context singletons, avoiding KV cache corruption and native crashes.
• Context warmup isolation — Warmup exchanges are cleared from the sequence after completion and gated behind the inference lock to prevent overlap with real requests.
• GPU memory leak fix — Properly dispose the native Vulkan/CUDA runtime (llamaInstance) on model unload — was previously only nulled, leaking GPU memory on every model switch.
• Windows device name guard — Block reserved device names (CON, NUL, PRN, AUX, COM0-9, LPT0-9) in config file path validation to prevent hang-on-read DoS.

Other

• Removed underperforming local models from the registry.
• Added email/GitHub fields and OS tracking to the issue feedback form.
• Added uninstall command documentation.

v0.3.10

Features

• Dashboard sync scheduling — Manage automatic sync schedules directly from the dashboard — enable/disable OS task scheduler, pick preset or custom intervals (including minute-level granularity), and view sync history with success/failure status.
• Missed sync detection — Dashboard warns when syncs were missed because the computer was off during scheduled times.

Bug Fixes

• Windows Task Scheduler — Fixed scheduling to work without admin elevation by using inline schtasks params instead of XML import.
• DML validation — Added SQL statement validation to prevent destructive queries, with improved error diagnostics for database operations.
• Currency formatting — Fixed crash when currency parameter is undefined during amount formatting.

Security

• Scheduler path validation — Added validateBinaryPath to reject shell metacharacters (&, |, $, etc.) and control characters in binary paths before passing them to OS schedulers (schtasks, cron, systemd, launchd).

Other

• Upgraded GitHub Actions to v5 across all CI workflows.

v0.3.9

Bug Fixes

• Dashboard port collision — Changed default dashboard port from 3000 to 45091 to avoid cookie collisions with other local dev servers (React, Express, Rails, etc.).

Other

• Streamlined installation with one-liner scripts for Windows, macOS, and Linux.
• Added SHA256 checksum generation to release workflow.

v0.3.8

Features

• Transaction pagination — Dashboard transaction table now supports server-side pagination with configurable page sizes (25/50/100), page number navigation with ellipsis, and scroll-to-top on page change.
• Provider credential update — New dialog in the dashboard to update login credentials for existing providers without re-adding them.
• Per-provider sync — Sync individual providers from the dashboard provider card menu instead of syncing all at once.
• Sync queue — Multiple sync requests are queued and processed sequentially with deduplication and a max queue depth of 10.
• 4-state auth status — Providers now show one of four authentication states (no credentials, pending, connected, expired) based on credential and sync history.
• CLI update check — Non-blocking version check with 24-hour cache notifies users when a new release is available.
• Getting started flow — New setup page with separate tabs for agent-assisted and manual configuration paths.
• Mobile dashboard navigation — Responsive page navigation and labels for mobile screens.

Security

• Timing-safe token comparison — Session token validation now uses crypto.timingSafeEqual to prevent timing attacks.
• Single-use URL token — The dashboard launch token in the URL is consumed on first use — replay from browser history is rejected.
• Dev-mode isolation — .dev-session file and Vite CORS origins are now gated behind KOLSHEK_DEV=1 environment variable, with automatic cleanup on exit.
• Secure cookie flag — Session cookie now includes the Secure attribute.
• Self-update integrity — Binary downloads are verified against SHA256 checksum sidecar files. Downloads abort on checksum mismatch or verification failure. HTTPS is enforced.
• XSS fix — Site feedback form now uses DOM API with GitHub URL allowlist instead of innerHTML.
• Enhanced error sanitization — Credential-like values in JSON format ("password":"value") are now redacted in error responses, with an expanded keyword list.
• Provider ID validation — Sync endpoint validates and coerces provider IDs to positive numbers, rejecting invalid input.
• SPA fallback hardening — Security headers (CSP, X-Frame-Options, etc.) now applied to the SPA index.html fallback response.
• Update check timeout — Background GitHub API check aborts after 5 seconds to prevent connection leaks.

Bug Fixes

• Sync error visibility — Error messages are now shown when individual providers fail during sync.
• Auth status threshold — Providers require 2+ consecutive sync failures before showing “expired” status — a single transient failure no longer triggers a false alarm.
• Sync queue dedup — Duplicate provider sync requests are deduplicated in the queue, and empty provider arrays are normalized.
• React performance — Fixed useCallback dependency on unstable mutation object in credential update dialog.
• Dead code cleanup — Removed unused isSyncing prop from provider grid components.

Other

• Security and liability disclaimer added to documentation.
• Documentation synced with codebase.

v0.3.7

Features

• React dashboard with client-side routing — Full SPA dashboard with 8 pages — overview, transactions, spending, trends, insights, categories, translations, and providers. Includes live sync progress panel, per-provider status tracking, and theme switching.
• Classification-based filtering — Transactions are now classified (expense, income, transfer, cc_billing, etc.) with filtering support across all report and trend endpoints.
• Custom classifications — Users can create and assign custom classifications beyond the built-in set via the dashboard classification panel.
• Real-time sync streaming — Bank sync now streams per-provider SSE events (start → progress → result → done) with live reconnection support for late-joining clients.

Security

• Session authentication — Dashboard requires a cryptographic token (generated at launch, exchanged for an HttpOnly/SameSite=Strict cookie) — no more open endpoints.
• CORS hardening — Replaced wildcard Access-Control-Allow-Origin: * with an explicit origin allowlist and exact-match validation.
• CSRF protection — All mutations reject requests with missing or non-allowlisted Origin headers.
• Path traversal prevention — Static file serving validates resolved paths stay within the build output directory.
• Content-Security-Policy — Added CSP header restricting scripts, styles, images, and connections to same-origin only.
• ReDoS prevention — User-supplied regex patterns are validated for length, nested quantifiers, and excessive alternation before compilation.
• Error sanitization — All API and SSE error responses strip file paths, stack traces, and internal details.
• Pagination limits — Transaction endpoints capped at 500 rows per request to prevent database dumps.
• Windows permission fix — Switched from Node’s child_process.spawnSync to Bun.spawnSync for reliable icacls permission hardening.

Bug Fixes

• Fixed sync endpoint mismatch — Client and server now agree on /api/v2/fetch route and SSE event types (start, progress, result, done).
• Fixed SSE reconnection — GET /api/v2/fetch/events now streams live events instead of returning a dead snapshot.
• Fixed Vite dev server auth — Added credentials: "include" on client and Access-Control-Allow-Credentials on server for cross-origin cookie support.
• Fixed duplicate favicon route — Removed dead code branch for /favicon.png that shadowed the /favicon.ico handler.

Other

• Removed legacy HTMX partials — Deleted all server-rendered HTML templates, styles, and layout files (~1,500 lines) in favor of the React SPA.
• Site polish — Updated favicon, added GitHub stars badge, footer credits, and improved nav/chat/theme toggle on the docs site.

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