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.

Flag	Description
--config PATH	Path to config file (default: ./config.yml, ~/.histerrc, or ~/.config/hister/config.yml)
--server-url URL / -u	Hister server URL (overrides server.base_url from config)
--token TOKEN / -t	Access token for server authentication (overrides app.access_token from config)
--log-level LEVEL / -l	Log level: error, warning, info, debug, trace (default: info)
--search-url URL / -s	Default search engine URL with {query} placeholder
--client-timeout N	HTTP client timeout in seconds for server communication (0 = no timeout; default if unset: 10s)

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

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

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, hister list-files, and most user administration commands.

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

Hybrid commands use or can use both local Hister state and the configured server. Examples include persistent hister index modes, hister import browser, hister list-urls --offline, and hister delete-user.

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 doctor
hister --server-url https://hister.example.com --token "$HISTER_TOKEN" doctor --format json

config create [FILENAME] writes default configuration to a new file, or prints YAML when no filename is given. It refuses to overwrite existing files. The deprecated create-config alias still works and prints a migration notice to stderr.

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 extractor extra 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.

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

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

Format	Output
text	The default human readable output for each command.
json	A JSON array of records, including an empty array when there are no results.
jsonl	One JSON object per line, with no surrounding array. No results produce no output.
csv	A header followed by records. Commas, quotes, and newlines in values are escaped.

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, 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:

Status	Meaning
0	Processing finished without reported item errors. Skipped items are allowed.
1	A setup, source, cancellation, output, or other execution error prevented completion.
2	Processing finished with item errors, including when every item failed.

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. Use unknown to clear a detected language. 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, language, or owner, so update the responsible collector or directory configuration when the change should remain permanent.

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

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

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: You do not need to run hister import file to add or track files configured in indexer.directories. After you add a directory to the configuration, restart the Hister server. The server scans the directory and starts watching it 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, and Linkwarden 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.

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 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:

Key	Action	Description
ctrl+c	quit	Exit the TUI
f1	toggle_help	Show/hide the complete keybindings help overlay
tab, esc	toggle_focus	Change focus or return to the previous workspace
up, k	scroll_up	Navigate up
down, j	scroll_down	Navigate down
enter	open_result	Open, edit, or submit the focused item
y	copy_result	Copy the selected URL using the terminal clipboard
v	toggle_preview	Show or hide the readable preview pane
l	edit_label	Edit the selected document’s label
ctrl+d	delete_result	Delete the selected item
ctrl+t	toggle_theme	Open the interactive theme picker
ctrl+s	toggle_settings	Open appearance and keybinding settings
ctrl+o	toggle_sort	Toggle domain-based sorting for search results
ctrl+e	toggle_semantic	Toggle semantic search when enabled in server config
alt+1	tab_search	Switch to the Search tab
alt+2	tab_history	Switch to the History tab
alt+3	tab_rules	Switch to the Rules tab
alt+4	tab_add	Switch to the Add tab

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.