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.

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:3000) 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.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