Home
TR
Reference

Command-Line Reference

Every end-user colpan command, grouped by area.

activity

  • colpan activity — What Colpan has been doing — a chronological feed of operations (previews, searches, indexing, OCR, …) with timing + outcome, read from the durable activity log on disk

cloud — Manage cloud sources (Google Drive, S3, WebDAV, …)

  • colpan cloud fetch <name> <uri> <out> — Fetch a single file to a local path
  • colpan cloud list — List all cloud sources defined in config.toml
  • colpan cloud ls <name> — List files under a remote path
  • colpan cloud stat <name> <uri> — Show metadata for a single cloud URI

config

  • colpan config show

convert — Convert documents between formats (via LibreOffice)

  • colpan convert file <input> <output> — Convert a file to another format
  • colpan convert formats — List supported formats
  • colpan convert to-pdf <input> — Convert a file to PDF

export

  • colpan export <query> — Export search results as JSON Lines (agent fine-tuning workflows)

filter — Filter presets (extensions, size limits, exclusions)

  • colpan filter add-ext <name> — Add extensions to a filter
  • colpan filter copy <source> <target> — Copy a builtin filter to a new editable filter
  • colpan filter create <name> — Create a new filter preset
  • colpan filter delete <name> — Delete a custom filter
  • colpan filter list
  • colpan filter remove-ext <name> — Remove extensions from a filter
  • colpan filter set-size <name> — Set size limits for a filter
  • colpan filter show <name>

group — Group (index) management - directories and rules

  • colpan group add-cloud-dir <group> <source> <remote_path> — Add a cloud directory backed by a defined cloud source
  • colpan group add-dir <group> <path> — Add directory to group
  • colpan group attach <profile> <group> — Attach group to a profile
  • colpan group clear-alias <group> — Clear alias from a group
  • colpan group create <group> — Create a new group
  • colpan group delete <group> — Delete a group
  • colpan group detach <profile> <group> — Detach group from a profile
  • colpan group disable <group> — Disable a group
  • colpan group enable <group> — Enable a group
  • colpan group exclude <group> <path> — Exclude a subdirectory
  • colpan group exclude-file <group> <path> — Exclude a specific file
  • colpan group export <group> <output> — Export group config to file
  • colpan group export-bundle <group> <output> — Export the full index (config + Tantivy data) as a .colpan ZIP bundle — the snapshot you publish to a shared folder for read-only distribution. Unlike export (config only), this carries the data. Run it while the group isn’t indexing so the snapshot is consistent. The write is atomic (temp + rename); if the destination is locked by a reader mid-copy, it waits up to —wait-secs before giving up
  • colpan group group-info <group> — Show group statistics
  • colpan group import <file> — Import group config from file
  • colpan group include <group> <path> — Re-include within excluded area
  • colpan group include-file <group> <path> — Include a specific file within excluded area
  • colpan group list — List all groups
  • colpan group list-rules <group> — List all rules for a group
  • colpan group publish <group> — Publish a group’s index now to its configured publish path — the manual “share now”. Skips when the index is unchanged unless —force
  • colpan group remove-dir <group> <path> — Remove directory from group
  • colpan group remove-rule <group> <path> — Remove a rule by path
  • colpan group rename <old> <new> — Rename a group
  • colpan group set-alias <group> <alias> — Set alias for a group
  • colpan group set-archive-ext <group> <ext> <formats> — Set or clear a per-extension archive scope override. Formats: “global” (inherit) | “none” | comma-list
  • colpan group set-archive-global <group> <formats> — Set the group’s global archive scope (formats expanded by default). Formats: “none” | “all” | comma-list of zip,rar,7z,tar,iso
  • colpan group set-description <group> <text> — Set description for a group
  • colpan group set-filter <group> <filter> — Set the filter preset for an existing group. Extensions, size limits, and exclude lists are resolved from the filter at index time — see `filter show <name>` for what will apply
  • colpan group set-language <group> <language> — Set this group’s document language for stemming. Lang: ISO code (“en”, “tr”, “de”) or a Snowball name (“english”); “auto” or “clear” follows the global indexing.stem_language / OS locale. Applies to the next (re)index — existing segments keep their analyzer
  • colpan group set-max-size <group> <ext> <size> — Set per-extension max size override. Size: “1KB”/“5MB”/… or “0”/“none” to clear
  • colpan group set-min-size <group> <ext> <size> — Set per-extension min size override. Size: “1KB”/“5MB”/… or “0”/“none” to clear
  • colpan group set-ocr-ext <group> <ext> <engine> — Set per-extension OCR engine override. Engine: off | auto | oar | tesseract | system | plugin:<name> | global (clear override)
  • colpan group set-publish <group> — Configure periodic read-only publishing for a group: a .colpan snapshot is written to —path every —every seconds (when the index has changed). 0 / —off = manual only (use group publish)
  • colpan group show <group> — Show group details

index — Build, inspect, and maintain search indexes

  • colpan index browse — Browse indexed files (list all documents in index)
  • colpan index delete-dir <path> — Delete all files in a directory from the index
  • colpan index delete-file <path> — Delete a file from the index by path
  • colpan index info — Show index statistics (format counts, sizes, top directories)
  • colpan index start
  • colpan index status

info

  • colpan info

models — Unified model pack catalog + downloader (OCR / LLM / NER). Replaces colpan ocr models … with a kind-aware surface

  • colpan models download <id> — Download a named pack — kind resolves automatically from the id
  • colpan models list — List every manifest plus install status. --kind filters
  • colpan models where — Where models live on disk (respecting config override)

ocr — Manage OCR engine selection and language

  • colpan ocr list — Full status — mode, engine, per-engine availability + langs, model installs
  • colpan ocr probe — Probe every engine with a tiny synthetic 4x4 image — CI-style sanity check that the registered backends respond without crashing
  • colpan ocr set-enabled <value> — Master on/off — equivalent to checking “Enable OCR” in the GUI
  • colpan ocr set-engine <engine> — Engine selection
  • colpan ocr set-language <language> — Language string (eng+tur | tur | …)
  • colpan ocr system langs — Show installed platform OCR languages (scaffold — empty list on unwired builds)

pii — Manage PII filter settings (categories, term allowlists)

  • colpan pii auto-scan <value> — Enable or disable auto-scan on preview open
  • colpan pii disable-category <category> — Disable a PII category (e.g. DATE, URL, IBAN, EMAIL, PHONE)
  • colpan pii disable-term <term> — Temporarily disable a custom term without removing it from the vault
  • colpan pii dismiss <term> — Dismiss a specific detected value (false-positive allowlist)
  • colpan pii enable-category <category> — Re-enable a previously disabled category
  • colpan pii enable-term <term> — Re-enable a disabled custom term
  • colpan pii show — Show current PII filter state (categories, terms, allowlist)
  • colpan pii undismiss <term> — Remove a term from the dismissed list
  • colpan pii vault clear — Truncate every entry + custom term in the vault. The vault_id and the master key are preserved (share/restore exports still resolve). Use this to wipe accumulated NER noise from a session of preview scans without nuking the master key
  • colpan pii vault export <path> — Export every vault entry to a CSV file (no tokens — see Import)
  • colpan pii vault import <path> — Import a category,original CSV produced by export or hand-written. Tokens are NOT in the file — they’re regenerated on insert with the active vault’s vault_id salt
  • colpan pii vault list — List vault entries (header + count + first N rows)

plugin — Inspect discovered plugins

  • colpan plugin disable <id> — Persistently disable a plugin (written to config.plugins.disabled). Takes effect next time the app/CLI loads
  • colpan plugin enable <id> — Re-enable a previously disabled plugin
  • colpan plugin list — List all discovered plugins with status
  • colpan plugin show <id> — Show full manifest for a single plugin

profile — Manage profiles (workspaces)

  • colpan profile add-dir <name> <path>
  • colpan profile create <name>
  • colpan profile delete <name>
  • colpan profile list
  • colpan profile remove-dir <name> <path>
  • colpan profile show <name>

search — Query the index

  • colpan search <query> — Query the index

search-saved — Manage saved (pinned) CQL search queries

  • colpan search-saved add <query> — Pin a CQL query for quick reuse. No-op if already saved
  • colpan search-saved list — Show every pinned search query, newest pin first
  • colpan search-saved remove <query> — Unpin a previously saved query. No-op if not present
  • colpan search-saved rename-category <old> <new> — Rename every entry whose category equals old to new. Empty new moves them into Uncategorized (which is a re-categorise, not a delete — pins survive)
  • colpan search-saved set-category <query> <category> — Move a saved query into a category bucket. Empty category drops it into “Uncategorized”. Errors if the query isn’t saved
  • colpan search-saved set-label <query> <label> — Set a friendly label for a saved query. Empty label renders the raw query. Errors if the query isn’t saved yet

settings — Desktop integration settings — autostart, start-minimized, tray-on-close

  • colpan settings autostart — PC startup auto-launch. Omit state to read current value
  • colpan settings mode — UI mode preset (built-in simple / advanced, or any [modes.<name>] defined in config.toml). Omit name to read
  • colpan settings show — Print every desktop_integration setting (config + actual OS state)
  • colpan settings start-minimized — Whether the autostart entry passes --minimized (start hidden)
  • colpan settings tray-on-close — X-button intercept: when on, X hides the window into the tray

starred — Manage starred collections

  • colpan starred add <collection> <path> — Add a file path to a collection
  • colpan starred create <collection> — Create a new empty collection
  • colpan starred delete <collection> — Delete a collection
  • colpan starred list — List all collections with item counts
  • colpan starred prune <collection> — Remove items whose paths no longer exist on disk
  • colpan starred remove <collection> <path> — Remove a path from a collection
  • colpan starred rename <old> <new> — Rename a collection
  • colpan starred show <collection> — Show items in a collection

status

  • colpan status — Live resource snapshot the running GUI mirrors to disk — loaded models / sessions / subprocesses with their RAM + CPU, plus active flows (indexing, OCR backfill, …)

watch — Watch for file changes and auto-reindex

  • colpan watch — Watch for file changes and auto-reindex