# Complete Guide to Hister CLI Commands for Server and Data Management

> Master Hister CLI commands for server and data management. Learn to listen, index, import, reindex, and cleanup with this comprehensive guide.

- Repository: [Adam Tauber/hister](https://github.com/asciimoo/hister)
- Tags: how-to-guide
- Published: 2026-08-27

---

**The `hister` binary exposes sub-commands for server lifecycle (`listen`), data ingestion (`index`, `import`), index maintenance (`reindex`, `cleanup`), and administrative tasks, all registered via the Cobra framework in [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go).**

The `asciimoo/hister` project provides a self-hosted document indexing and search platform controlled entirely through a command-line interface. Mastering the **Hister CLI commands** allows administrators to launch services, recursively crawl websites, import bookmark collections, and perform essential housekeeping without writing custom scripts.

## Server Lifecycle Management

### Starting the HTTP Server with `listen`

The `listen` sub-command boots the HTTP API and optional file system watchers. Defined in [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go) within the command run block ([lines 59-63](https://github.com/asciimoo/hister/blob/master/cmd/root.go#L59-L63)), it delegates to `server.Listen` in [`server/server.go`](https://github.com/asciimoo/hister/blob/main/server/server.go) to initialize the indexer, configure routes for document CRUD and search endpoints, and bind to the address specified in `cfg.Server.Address`.

To start the server on a custom port with public access:

```bash
hister listen --address 0.0.0.0:8080 --public

```

## Indexing and Crawling Commands

### One-Off URL Indexing

The `index` command, implemented in [`cmd/index.go`](https://github.com/asciimoo/hister/blob/main/cmd/index.go), adds individual URLs to the search index. It checks for duplicates using the `crawlerSkipOptions` logic ([lines 97-111](https://github.com/asciimoo/hister/blob/master/cmd/index.go#L97-L111)) unless the `--force` flag is provided, and submits documents via `client.AddDocumentJSON`.

```bash

# Index a single URL (skips if exists)

hister index https://example.com

# Force re-indexing to overwrite existing entries

hister index --force https://example.com

```

### Recursive and Persistent Crawling

Supplying the `--recursive` flag transforms the operation into a persistent crawl job stored in `model.CrawlJob`. The crawl loop resides in `crawlAndIndex` ([lines 58-81](https://github.com/asciimoo/hister/blob/master/cmd/index.go#L58-L81)), which respects `crawlerSkipOptions` for duplicate detection. Administrators can resume interrupted jobs by specifying an existing `--job-id` without the `--recursive` flag.

```bash

# Start a recursive crawl with a specific job ID

hister index --recursive --job-id myjob https://myblog.com

# Resume the crawl later from the saved queue state

hister index --job-id myjob

```

### Managing Crawl Jobs and Reindexing

The `crawl` command inspects and manages persistent crawl jobs (list, show, delete), while `reindex` rebuilds the entire index—essential after modifying analyzer settings or language detection configurations.

```bash

# Rebuild the index after configuration changes

hister reindex

```

## Data Import and Export Workflows

### Importing from External Services

The `import` command aggregates service-specific importers for Linkding, Wallabag, Shaarli, and browsers. Registered in [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go) ([lines 82-86](https://github.com/asciimoo/hister/blob/master/cmd/root.go#L82-L86)), each sub-command (e.g., `import linkding`) accepts flags defined by `addServiceImportFlags` ([lines 29-34](https://github.com/asciimoo/hister/blob/master/cmd/root.go#L29-L34)). The import flow constructs a crawler backend via `applyCrawlerBackendFlags` (supporting HTTP, ChromeDP, or Bidi), retrieves bookmarks from the external API, and pipes them through the standard indexing pipeline.

```bash

# Import from Linkding using an environment variable for the API token

hister import linkding --api-token "$LINKDING_TOKEN"

```

### Exporting Document Archives

The `export` command streams documents from the server to stdout or a file, supporting `text`, `json`, and `csv` formats. It accepts `--start-date` and `--end-date` filters and invokes the client's `ExportDocuments` endpoint.

```bash

# Export the entire index to a JSON backup file

hister export --format json > hister-backup.json

```

## Maintenance and Administrative Tasks

### Document Cleanup and Deletion

The `delete` command removes documents matching query parameters, requiring explicit confirmation or the `--yes` flag for safety. The `--dry` flag enables simulation mode to preview deletions. The `cleanup` command performs deeper housekeeping, purging orphaned files, expired crawl jobs, and stale metadata from the database.

```bash

# Simulate deletion of documents older than 2022-01-01

hister delete --end-date 2022-01-01 --dry

# Prune orphaned data and expired jobs

hister cleanup

```

### User Management and System Utilities

Administrators can manage local users through `create-user`, `show-user`, `update-user`, and `delete-user` commands. The `search` command allows direct CLI queries against the index, and `check-update` queries the GitHub releases feed to verify version currency.

## Global Configuration and Client Architecture

All sub-commands share global flags defined in [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go), including `--config` for configuration files, `--log-level` for verbosity, and `--token` for authentication. Each command constructs an RPC client using the `newClient` helper ([lines 78-89](https://github.com/asciimoo/hister/blob/master/cmd/root.go#L78-L89)) defined in the same file, ensuring consistent communication with the server via [`client/client.go`](https://github.com/asciimoo/hister/blob/main/client/client.go).

## Summary

- The `listen` command in [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go) initializes the HTTP server and indexer, binding to `cfg.Server.Address`.
- Use `index` for one-off URL addition or persistent recursive crawling, with duplicate detection handled by `crawlerSkipOptions` in [`cmd/index.go`](https://github.com/asciimoo/hister/blob/main/cmd/index.go).
- The `import` command supports multiple bookmark services via flags defined in `addServiceImportFlags`, using crawler backends configured through `applyCrawlerBackendFlags`.
- Maintenance tasks like `reindex`, `cleanup`, and `delete` utilize the shared `newClient` RPC helper to interact with the server.
- Global flags `--config`, `--log-level`, and `--token` apply to all sub-commands in the Cobra-based CLI structure.

## Frequently Asked Questions

### How do I resume an interrupted crawl job in Hister?

Supply the existing `--job-id` to the `index` command without the `--recursive` flag. Hister loads the persisted queue state from the database and continues processing URLs from where the previous execution stopped.

### What is the difference between `cleanup` and `delete` commands?

The `delete` command removes specific documents matching query criteria (e.g., date ranges), while `cleanup` performs system-wide housekeeping by purging orphaned files, expired crawl jobs, and stale metadata that no longer reference valid documents.

### Can I import bookmarks from services not listed in the Hister documentation?

Yes, if the service provides a standard export format (like HTML bookmarks or API access). The `import` command structure in [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go) is extensible, allowing developers to add new service importers using the existing `addServiceImportFlags` pattern and `applyCrawlerBackendFlags` for content retrieval.

### Where are the HTTP server routes defined when running `hister listen`?

The `listen` command delegates to `server.Listen` in [`server/server.go`](https://github.com/asciimoo/hister/blob/main/server/server.go), which configures routes for search, document CRUD operations, and user management, while [`cmd/root.go`](https://github.com/asciimoo/hister/blob/main/cmd/root.go) ([lines 59-63](https://github.com/asciimoo/hister/blob/master/cmd/root.go#L59-L63)) handles the command initialization and indexer setup.