Terminal Client

See also the configuration documentation.

Global Flags

These flags are accepted on every command for compatibility. Subcommand help only displays the flags that affect that command.

Example: index a slow extractor, such as yt-dlp, with a longer timeout:

hister --client-timeout 20 index https://example.com

When using an access token, set --server-url or server.base_url to the final server address. Authenticated commands refuse redirects to another host or port, or between HTTP and HTTPS, to keep your token on the selected server.

Execution Scope

Root help groups Hister operations by scope, and each operation help page identifies where the command operates:

Local commands use configured files or local Hister data directly and do not contact the configured Hister HTTP server. Examples include hister crawl list and hister list-files.

Remote commands use the configured Hister HTTP server without opening the local Hister database or search index. Examples include hister search, hister export, hister cleanup, hister user show, hister user update, and hister user delete.

Hybrid commands use or can use both local Hister state and the configured server. Examples include persistent hister index modes, hister import browser, and hister list-urls --offline. hister user create also belongs to this group: it uses the server by default and creates an account directly in the configured database only with --offline.

Use the scope label before running a command against a remote deployment. Local commands operate on the data directory selected by the local configuration even when --server-url is supplied.

Command-Line Usage

View all available commands:

./hister help

Check for Updates

Check whether a newer Hister release is available:

hister check-update

The command displays the installed version and the latest published version when an update is available. It also provides a link to the release. When Hister is current, the command reports that it is up to date.

This check requires internet access. It does not download or install the update.

Configuration and Diagnostics

hister config create ~/.config/hister/config.yml
hister config path
hister config show
hister --config /etc/hister/config.yml config validate
hister reload
hister doctor
hister --server-url https://hister.example.com --token "$HISTER_TOKEN" doctor --format json

reload applies updated settings to the running server, including logging changes. Expect a brief interruption and refresh open Hister web pages afterwards. An admin token is required in multi user mode. See Reloading a Running Server for examples and limitations.

config create [FILENAME] writes all default settings as commented YAML to a new file, or prints them when no filename is given. Uncomment a setting and its enclosing section to activate it, preserving indentation and leaving unrelated settings commented. Use config create --full [FILENAME] to write all defaults as active YAML values. Both forms refuse to overwrite existing files and work without a valid current configuration.

config path prints the absolute path of the selected main config file, or (defaults) when no file is found. It works even when the file contains invalid YAML. config show prints effective YAML after applying defaults, environment variables, and global flags. It redacts credentials, header and cookie values, URL credentials and query values, PostgreSQL connection strings, and external command arguments. Separate rules.json and tui.yaml files are not included.

config validate checks main configuration keys and value types, supported settings, hotkeys, OAuth, public mode, semantic search settings, and extractor names and options. It exits with status 1 on an error and 0 on success. It does not test network access or executable availability.

These inspection commands do not create data directories, secret keys, rules, TUI files, or log files. They follow the normal config search order. An explicit --config or HISTER_CONFIG path must exist, and unreadable files are reported instead of silently falling back to defaults.

doctor checks local configuration and enabled extractor executables, then verifies server connectivity and authentication. The server checks its own index version, analyzer and embedding configuration fingerprints, and extractor executables. This supports remote deployments without opening a local index. Currently, yt-dlp is the extractor that requires an external executable. The executable is located without running it. Doctor does not repair data or call an embedding provider.

Server checks use GET /api/diagnostics. Token authentication is required when configured, including in public mode. Multi user deployments require an admin token. Older servers report a warning when diagnostics are unavailable. Use --client-timeout to control the HTTP timeout for each request.

Doctor supports --format / -f with text, json, jsonl, or csv. Each record contains name, status, and message. Status is ok, warning, or error; check names use local. or server. prefixes where applicable. Exit status is 1 if any check fails, and 0 when all completed checks pass or only warnings remain. JSON output remains a complete array when a diagnostic check reports an error.

Maintenance

hister reindex
hister cleanup

Both commands require a running server. reindex rebuilds search indexes from stored documents. cleanup removes indexed local documents that no longer match configured directories, plus unreferenced preview and favicon files. See Data Storage and Lifecycle for details about what cleanup removes.

Both commands print a start message and a completion message with elapsed time to stderr. When stderr is connected to an interactive terminal, a timer updates every second while the command waits for the server to finish. Redirected stderr contains plain messages without timer updates. A failed operation reports an error without printing a completion message.

Cleanup also prints its checked, skipped, and removed counts to stdout, so you can save those results separately:

hister cleanup > cleanup-results.txt

Purge Retained Data

Preview old stored versions, unpinned opened result history, and completed crawl records:

hister purge --versions --history --crawl-jobs --before 2026-01-01 --dry

Select one or more categories and a --before date or RFC3339 timestamp. Omit --dry to preview and then confirm deletion, or add --yes to skip confirmation. The operation requires a running server and administrator access in multi user mode, and applies across all users. Current documents remain searchable. See Purging Retained Data for the cutoff rules and retained records.

Index a URL Manually

To manually index a specific URL:

./hister index https://example.com

For persistent recursive crawls, URL input jobs, custom job names, resume behavior, request backends, and every crawl subcommand, see Website Crawler.

Search Output And Scripting

Provide search terms to print results. Use --fields to select fields and --limit to stop after a given number of documents:

hister search 'language:en' --format json --fields title,url --limit 20
hister search 'domain:example.com' --format jsonl --fields url,text
hister search 'label:research' --format csv --fields title,url > research.csv

By default, text output shows only the title and URL. Use --fields text (or -F text) to print the complete stored text without truncation. JSON, JSONL, and CSV include the complete text by default. Selecting fields such as --fields title,url omits the text. HTML is included only when selected with --fields html, which can be combined with other fields, for example --fields url,text,html.

When a text search finds no matches in an interactive terminal, Hister prints a message with a spelling suggestion when available, or a hint to broaden the search. An empty search result still exits successfully. Redirected or piped text output stays empty, and structured formats keep the output described below.

Search, indexing summaries, crawl inspection commands, doctor, and file and service import summaries share --format / -f:

JSON always uses an array, including commands that return one job, count, or import summary. Unknown format names are rejected. Search preserves the selected field order in CSV and text. Structured records contain plain data without terminal styling.

Command errors are written to stderr. Search results stream as pages arrive, so a failed request can leave partial output. Check the exit status before treating a result as complete. JSON arrays are closed only when the search succeeds; JSONL retains complete records from earlier pages.

File and service imports can emit a summary with numeric imported, skipped, and errors fields:

hister import file backup.json --format json
hister import linkding https://bookmarks.example.com --format jsonl

These formats apply to file imports and the Linkding, Linkwarden, Karakeep, Raindrop, Readeck, Readwise Reader, Shaarli, and wallabag importers. Browser import retains its interactive output. See Website Crawler for structured crawl inspection.

Indexing Results And Exit Status

Indexing reports indexed, skipped, and failed counts. Already indexed URLs and URLs excluded by robots.txt count as skipped. Individual URL failures do not stop the remaining URLs:

hister index https://example.com/one https://example.com/two --format json
hister index --input urls.txt --failed-urls failed-urls.txt

The exit statuses for index, import file, and service imports are:

File and service imports retain their imported, skipped, and errors summary fields. A service import also prints its accumulated counts if fetching a later source page fails, then exits with status 1. Content extraction errors can count toward errors even if bookmark metadata was successfully imported. Optional favicon download failures remain diagnostic messages.

The index --failed-urls PATH option writes one failed URL per line and replaces the file’s contents. It creates an empty file when there are no failed URLs. An unusable report path fails before indexing starts. Retry the saved URLs with:

hister index --force --input failed-urls.txt --failed-urls still-failed.txt

Persistent indexing summaries include job_id and pending. Their counts describe the entire stored job, including earlier runs and redirect tracking URLs, rather than only the current run. The retry file likewise contains all URLs currently marked failed in that job. A completed job with stored failures continues to return status 2 when resumed without more pending work. Stopping at a configured crawl limit can leave pending URLs without being an error.

Updating Document Attributes

Use hister update to change attributes on every document selected by the query language:

hister update 'user_id:0' --user-id 2
hister update 'domain:example.com' --label research
hister update 'language:unknown' --language en

The supported attributes are user_id, label, title, and language. Pass an empty label or title to clear it. A language choice remains pinned across reindexing and resubmission. Known language codes such as en-US, nb, and uk are accepted. Support for matching related word forms varies by language, but documents remain searchable. Use unknown to keep a document without an identified language, or auto to clear the pin and identify the language from saved content using the running server’s detection settings. Hister reports the number of matching, changed, unchanged, and conflicting documents.

The command previews the operation and asks for confirmation. Use --dry to preview without applying changes, or --yes to apply immediately:

hister update 'label:inbox' --label archive --dry
hister update 'label:inbox' --label archive --yes

Changing user_id requires administrator access. User ID 0 is reserved for global documents and does not represent a user account. Documents indexed before user handling was enabled normally belong to user ID 0. Global documents are visible to every authenticated user and, when public mode is enabled, to anonymous visitors. Use user_id:0 in the query to select global documents. Use --user-id 0 as the change to make matching documents global.

An ownership change never overwrites a document that already has the same URL and destination owner. Those documents are reported as conflicts and skipped. Stored version records move with a changed owner, while search history stays with the user who created it.

For a watched local file, its configured directory user must match the destination owner. Future indexing can replace a manually changed title or owner, so update the responsible collector or directory configuration when the change should remain permanent.

Language pins also survive watched file updates and export/import. They apply only to the selected documents and their owners. See Language Settings and Detection for examples of pinning and clearing languages.

Exporting Documents

Use hister export to write indexed documents to a JSON file. This is useful for backups or for moving documents between Hister instances. By default every indexed document is exported:

hister export backup.json

If the output filename has no extension, Hister appends .json automatically. For example, hister export backup writes backup.json. Explicit extensions are preserved, including .JSON. Other extensions produce a warning because the file importer expects .json. The success message shows the actual output filename.

An existing export stays unchanged until the new export is complete. If fetching or saving fails, the command reports an error and keeps the previous file. Allow enough free space for both exports during replacement. Saved exports are readable and writable only by their owner on Unix systems. The destination must be a regular file or a new filename; symbolic links, directories, and special files are rejected.

You can limit the export to documents matching a search query by passing it after the output file (see the query language reference):

hister export rust.json "rust language:en"

Each document is written as a single JSON line; lines that do not start with { are structural markers ([, ], ,) and can be safely skipped by parsers. Pass - as the output file to write to standard output instead, which can be piped into other tools:

hister export - | gzip > backup.json.gz

Standard output can contain partial data if an export fails. Shell redirection also replaces its destination before Hister runs. To preserve an existing export until its replacement succeeds, pass the filename directly to hister export.

Use --start-date / --end-date (YYYY-MM-DD) to only export documents whose updated timestamp falls within the given date range. The resulting file can be re-imported with hister import file (see below).

Importing Documents

Use hister import file to add documents from files on disk. It accepts an arbitrary number of files or directories, which are imported in order and reported as a combined total:

Important: Use hister import file to restore Hister JSON exports, including exports in 7z archives, regardless of whether the server can access them.

For ordinary documents such as PDFs, notes, and text files, importing is only needed when the Hister server cannot access the files directly. Otherwise, use local file indexing. Configure indexer.directories and restart the server to scan and watch those directories automatically.

hister import file export.json page.html ~/Downloads/saved-pages

Several input formats are supported:

• JSON export files files previously created by hister export. They are read line by line and each serialized document is restored without running content extraction again.
• 7z archives (.7z) a 7z compressed archive containing a single JSON export file.
• HTML files (.html or .htm) a saved web page. The document URL is extracted from the HTML itself (the <link rel="canonical"> tag, OpenGraph/Twitter url meta tags, etc.) and the page is submitted to the running server for processing.
• Local file snapshots PDF, DOCX, Markdown, Org mode, HTML without source URL metadata, JSON without the Hister export array shape, and valid UTF 8 text are extracted locally. Only prepared document fields are sent to the server.

When a directory is passed, Hister imports matching files recursively. With no input, it creates remote file snapshots from configured watched directories and applies their filters. Use this mode only when the command line client can read those directories but the server cannot. Add --watch to keep importing new and changed snapshots while the command is active. Source removals retain the indexed snapshots.

# Import a single saved web page
hister import file ~/Downloads/article.html

# Import all supported files recursively from a directory
hister import file ~/Downloads/saved-pages

# Create snapshots when the server cannot access configured directories
hister import file

Useful flags:

• --skip-existing do not overwrite documents that are already in the index.
• --start-date / --end-date (YYYY-MM-DD) only import documents whose added timestamp falls within the given date range (applies to JSON exports).
• --batch-size controls how many documents are submitted in each bulk request. The default is 10 and the maximum is 100.
• --source sets the stable source namespace for remote file snapshot URLs.
• --watch performs an initial scan and continues importing new and changed snapshots until interrupted. --skip-existing applies only to the initial scan. Watch mode skips exports, 7z archives, and saved HTML with source URLs, and cannot be combined with date filters.
• --allow-sensitive skips sensitive content checks for imported snapshots.

Note: hister import file talks to a running Hister server, so make sure the server is started before importing. See Importing Documents for file, browser history, browser bookmark, and reading service import instructions.

hister import file creates searchable snapshots when the server cannot read files directly. Snapshot extraction occurs locally and only the prepared document is sent through the normal add API. It is not needed for normal local file tracking. Starting or restarting the server scans every configured directory and starts its file watcher automatically. With no paths, the command creates snapshots for every file matched by configured watched directories. Explicit directories are recursive.

hister import file
hister import file --source work-laptop ~/notes ~/Documents/report.pdf
hister import file --watch --source work-laptop ~/notes

The command extracts the same PDF, DOCX, Markdown, Org mode, and plain text formats used by watched directories. It does not send the original bytes. Run the command again to replace a snapshot with the same source name and absolute path, or use --watch to update snapshots while the command runs. Watch mode retries temporary server failures, prints a combined summary on exit, and scans all inputs again on restart. Source removals never delete remote snapshots, including when delete_on_remove is configured. See Importing Documents for details.

List Watched Files

hister list-files
hister list-files --relative

This command lists files matching the configured directory watch rules. It does not check file contents or report indexing status. The list includes files that indexing rejects because of sensitive content, size, or format checks.

Sensitive content rejections produce a warning in the server logs at the default log level, with the file path and no matched content. Rejected files remain watched and are checked again when they change.

Importing Browser History and Bookmarks

Use the browser subcommands to import visit history or saved bookmarks into a running Hister server:

# Import visit history from Firefox
hister import browser history --browser firefox

# Import saved bookmarks from Firefox
hister import browser bookmarks --browser firefox

# Import a specific Chromium bookmark store
hister import browser bookmarks --db ~/.config/google-chrome/Default/Bookmarks

Omit --browser and --db to detect all supported browser profiles. The bare hister import browser command also imports history. History documents use the browser label and bookmark documents use bookmarks; use --label LABEL to override either default.

Both importers fetch the current page contents and keep persistent crawl jobs that can resume after interruption. See Importing Browser History and Importing Browser Bookmarks for supported browsers and options.

TUI (Terminal UI)

Hister provides a terminal-based user interface for searching your browsing history without leaving your terminal.

Start the TUI

Run the search command without any arguments:

hister search

TUI Features

• Multi-tab interface: Search, History, Rules, and Add tabs
• Mouse support: Scroll with mouse wheel, click to select, right-click for context menu
• Result actions: Copy URLs, read full previews, edit labels, prioritize, or delete
• Responsive preview pane: Read results beside the result list on wide terminals; smaller terminals switch the preview to full width
• Semantic search: Toggle hybrid keyword/semantic results when semantic search is enabled
• Theming: Built-in color themes with interactive picker (press ctrl+t)
• Settings overlay: Change appearance mode or edit keybindings interactively (press ctrl+s)
• Responsive workspaces: Every tab scrolls and adapts to the terminal size
• Contextual help and feedback: Footer shortcuts match the active tab, while notices confirm actions

Tabs

• Search (Alt+1): Main search interface
• History (Alt+2): View your recent search history
• Rules (Alt+3): Manage allow, skip, priority, versioning, and alias rules
• Add (Alt+4): Manually add URLs, titles, and multiline text to the index

TUI Keybindings

The TUI uses the following keybindings by default:

Mouse Controls

• Left-click: Select results or open tabs
• Right-click: Open the result menu (open, copy, details, label, prioritize, delete)
• Scroll wheel: Navigate results or scroll the active workspace/overlay
• Scrollbar drag: Quick scroll through long result lists

When a preview is open on a wide terminal, use tab to move focus between the result list and the preview. Arrow keys or j/k then navigate the focused side. Clicking or scrolling either side focuses it. Press v, esc, or the × in the preview header to close it.

Search input and result navigation are separate focus modes. While the search field is focused, printable keys edit the query and the footer only shows input actions. Press down or tab, or scroll/click inside the results, to focus the result list; result shortcuts such as y and v then become available.

Customizing TUI

TUI settings are stored in a separate tui.yaml file alongside your main config file. This file is automatically created with default values when you first run hister search.

On a typical Linux setup the path is ~/.config/hister/tui.yaml. On other platforms, or when a custom config path is selected, tui.yaml is stored beside the main config file.

tui.yaml Structure

# Theme settings
dark_theme: 'tokyonight'
light_theme: 'catppuccin-latte'
color_scheme: 'terminal'
# themes_dir: "/path/to/custom/themes"  # optional

# TUI keybindings
hotkeys:
  ctrl+c: 'quit'
  ctrl+t: 'toggle_theme'
  ctrl+s: 'toggle_settings'
  ctrl+o: 'toggle_sort'
  ctrl+e: 'toggle_semantic'
  y: 'copy_result'
  v: 'toggle_preview'
  l: 'edit_label'
  alt+1: 'tab_search'
  alt+2: 'tab_history'
  alt+3: 'tab_rules'
  alt+4: 'tab_add'
  # ... and all other TUI keybindings

terminal is the default appearance. It leaves your terminal background and normal text color untouched and uses your terminal’s ANSI palette for accents. Use auto to select the configured dark or light Hister theme based on the terminal background, or choose dark or light explicitly. Press ctrl+s and select Appearance to cycle these modes from Settings; ctrl+t opens the full theme picker.

Available TUI Actions

• quit - Exit the TUI application
• toggle_help - Show/hide the help overlay
• toggle_focus - Change focus or return to the previous workspace
• scroll_up/scroll_down - Move selection up/down
• open_result - Open selected URL in browser
• copy_result - Copy the selected URL
• toggle_preview - Show/hide selected result details
• edit_label - Edit the selected document label
• delete_result - Delete selected entry from index
• toggle_theme - Open theme picker
• toggle_settings - Open appearance and keybinding settings
• toggle_sort - Toggle sorting mode
• toggle_semantic - Toggle semantic search
• tab_search/tab_history/tab_rules/tab_add - Switch tabs

Note: After modifying tui.yaml, restart the hister search command to apply changes.