CLI Commands

The OpenObserve binary (./openobserve) ships with a set of maintenance subcommands that operators run from the command line to reset data, clean up storage, migrate metadata, and inspect a running cluster.

Overview

These commands operate directly against the OpenObserve database and object storage, outside of the regular ingestion and query paths. You run them from the same host and with the same environment variables (for example ZO_ROOT_USER_EMAIL, ZO_ROOT_USER_PASSWORD, and your object storage settings) as a running OpenObserve node, because the binary reads its configuration the same way the server does.

Most subcommands follow the pattern ./openobserve <command> [options]. Run a command with no required arguments to see its usage, or run ./openobserve --help to list all subcommands.

Several of these commands modify or delete data. Read the safety notes for each command before running it in production, and prefer dry-run mode where it is available.

Command summary

Command	Purpose
`reset -c <component>`	Reset data for a component (root user, alerts, dashboards, functions, stream stats, file list jobs, and more).
`gc-file-list`	Delete stale stream files left on remote object storage past data retention.
`recover-file-list`	Rebuild the file list from files found in remote object storage.
`migrate-file-list`	Migrate `file_list` tables between databases.
`migrate-meta`	Migrate metadata tables between databases (excludes `file_list` tables).
`delete-parquet`	Delete a single parquet file from object storage and the file list.
`view -c <component>`	Print the stored version or the cached user list.
`node <subcommand>`	Manage and inspect cluster nodes.
`sql -e <query>`	Run an ad hoc SQL query from the command line.

reset

The reset command resets data for a single component. The component is selected with -c / --component.

./openobserve reset -c <component>

Available components:

Component	What it resets
`root`	Resets the root user using `ZO_ROOT_USER_EMAIL` and `ZO_ROOT_USER_PASSWORD`.
`user`	Resets user data.
`alert`	Resets alerts.
`dashboard`	Deletes all dashboards.
`report`	Resets reports.
`function`	Resets functions.
`stream-stats`	Resets the stream stats offset and recalculates stats from the file list.
`file-list-jobs`	Re-queues file list jobs and resets compact offsets so compaction reruns over historical data.
`index-updated-at`	Resets the index `updated_at` watermark for a stream.

reset -c root

Resets the root user account. The new password is taken from ZO_ROOT_USER_PASSWORD and must meet the configured password policy, otherwise the command fails.

./openobserve reset -c root

Note: Set ZO_ROOT_USER_EMAIL and ZO_ROOT_USER_PASSWORD in the environment before running this command. The email identifies the account to reset and the password becomes its new password.

reset -c file-list-jobs

Re-runs compaction over a stream's historical file list. The command re-queues file_list_jobs rows to the pending state and resets the compact offsets, so the compactor processes the affected files again.

./openobserve reset -c file-list-jobs [-t <microseconds>] [-s <org/stream_type/stream_name>]

Options:

Option	Description	Default
`-t`, `--time`	Reset offsets and re-queue jobs from this timestamp, in microseconds.	`0`
`-s`, `--stream`	Limit the reset to a single stream, in the form `org/stream_type/stream_name`.	All streams

What the command does:

Checks the cluster for online dedicated compactor nodes and aborts with an error naming them if any are found.
If a single_node (Role::All) node is online, prints a warning that it must be restarted after the reset.
Resets the compact file offsets in the meta table to the supplied time.
Sets matching file_list_jobs rows back to pending so they are picked up again.

Examples:

# Re-run compaction for all streams from the beginning
./openobserve reset -c file-list-jobs

# Re-run from a specific microsecond timestamp
./openobserve reset -c file-list-jobs -t 1700000000000000

# Limit to a single stream
./openobserve reset -c file-list-jobs -s default/logs/app

# Combine time and stream
./openobserve reset -c file-list-jobs -t 1700000000000000 -s default/logs/app

Warning: Stop all dedicated compactor nodes before running this command. The command refuses to run while a compactor is online to avoid concurrent processing of the jobs it is re-queuing.

Warning: If you run a single_node (all-in-one) deployment, restart those nodes after the command finishes so their in-memory compact state is cleared.

reset -c index-updated-at

Resets the index updated_at watermark. With no options it applies to all streams and uses each stream's minimum data date.

./openobserve reset -c index-updated-at [-t <microseconds>] [-s <org/stream_type/stream_name>]

Options:

Option	Description	Default
`-t`, `--time`	Timestamp in microseconds.	Stream minimum data date
`-s`, `--stream`	Limit to a single stream, in the form `org/stream_type/stream_name`.	All streams

gc-file-list

Deletes stale stream files left on remote object storage that are past their data retention. The compactor retention job marks files as deleted in the file_list table but can fail to remove the physical objects from storage, leaving orphaned files behind. This command cleans up that leftover data.

./openobserve gc-file-list [-a <account>] [-s <org/stream_type/stream_name>] [-d]

Options:

Option	Description	Default
`-a`, `--account`	Override the storage account used to list and delete. Required for `file_hash` multi-account setups.	Resolve per stream
`-s`, `--stream`	Clean only a specific stream, in the form `org/stream_type/stream_name`.	All streams
`-d`, `--dry-run`	Print what would be deleted without touching storage.	Off

How it decides what to delete:

The effective retention for a stream is its data_retention setting, falling back to ZO_COMPACT_DATA_RETENTION_DAYS.
It deletes date directories whose data is entirely past the retention cutoff, so the boundary day is always preserved.
It preserves any day that overlaps an extended retention range.

Examples:

# All streams
./openobserve gc-file-list

# A single stream
./openobserve gc-file-list -s default/logs/mystream

# Preview deletions for a single stream
./openobserve gc-file-list -s default/logs/mystream -d

# Override the storage account (file_hash multi-account setups)
./openobserve gc-file-list -a account2

Warning: This command permanently deletes objects from remote storage. Run it with -d / --dry-run first and review the output before running it for real.

Note: gc-file-list only works with remote object storage (s3, gcs, azure). It errors out on local disk storage.

Note: Streams with an effective retention of 1 day or less are skipped as a safety guard, so the command never deletes near-current data.

recover-file-list

Rebuilds the file list from parquet files found under a prefix in remote object storage. Use this to recover the file_list after metadata loss.

./openobserve recover-file-list -a <account> -p <prefix> [-i]

Options:

Option	Description	Required
`-a`, `--account`	The storage account name.	Yes
`-p`, `--prefix`	Only process the given prefix.	Yes
`-i`, `--insert`	Insert the recovered file list into the database. Without this flag the command only reports what it finds.	No

# Preview what would be recovered under a prefix
./openobserve recover-file-list -a default -p files/default/logs/app/

# Recover and insert into the database
./openobserve recover-file-list -a default -p files/default/logs/app/ -i

migrate-file-list

Migrates the file_list related tables between databases, for example from SQLite to PostgreSQL.

./openobserve migrate-file-list -f <from> -t <to> [options]

Options:

Option	Description	Default
`-f`, `--from`	Source database: `sqlite` or `postgresql`.	Required
`-t`, `--to`	Target database: `sqlite` or `postgresql`.	Required
`-b`, `--batch-size`	Batch size for migration.	`1000`
`--tables`	Only migrate the specified tables (comma-separated).	All
`--exclude`	Exclude the specified tables (comma-separated).	None
`--truncate-target`	Truncate target tables before migration.	Off
`--incremental`	Run in incremental mode.	Off
`--since`	Incremental start time, in microseconds.	None
`--dry-run`	Only print the plan, do not execute.	Off

./openobserve migrate-file-list -f sqlite -t postgresql

migrate-meta

Migrates metadata tables between databases. This excludes the file_list tables, which are handled by migrate-file-list. It accepts the same options as migrate-file-list.

./openobserve migrate-meta -f <from> -t <to> [options]

./openobserve migrate-meta -f sqlite -t postgresql

delete-parquet

Deletes a single parquet file from object storage and removes its entry from the file_list.

./openobserve delete-parquet -f <file> [-a <account>]

Options:

Option	Description	Required
`-f`, `--file`	The parquet file name to delete.	Yes
`-a`, `--account`	The storage account name.	No

view

Prints stored data for inspection. The component is selected with -c / --component.

./openobserve view -c <component>

Component	What it prints
`version`	The stored schema/data version.
`user`	The cached user list.

node

Manages and inspects cluster nodes.

./openobserve node <subcommand>

Subcommand	Description
`offline`	Mark the node offline.
`online`	Mark the node online.
`flush`	Flush the memtable to disk.
`status`	Show node status.
`list`	List cached nodes. Add `-m` / `--metrics` to include node metrics.
`metrics`	Show local node metrics.
`reload`	Reload cache from the database. Use `-m` / `--module` with a comma-separated list of modules (for example `schema,user,functions`).

# List cached nodes with metrics
./openobserve node list --metrics

# Reload specific caches from the database
./openobserve node reload -m schema,user,functions

sql

Runs an ad hoc SQL query from the command line.

./openobserve sql -e "<query>" [-o <org>] [-t <time>] [-l <limit>]

Options:

Option	Description	Default
`-e`, `--execute`	The SQL query to run.	Required
`-o`, `--org`	Organization name.	`default`
`-t`, `--time`	Time range, for example `15m`, `1h`, `1d`, `1w`, `1y`.	`15m`
`-l`, `--limit`	Maximum number of results (1–1000).	`10`

./openobserve sql -e "SELECT * FROM logs" -o default -t 1h -l 50

Best practices

Run destructive commands (reset, gc-file-list, delete-parquet) against a non-production environment first to confirm the behavior.
Always use --dry-run with gc-file-list before a real run.
Stop dedicated compactor nodes before reset -c file-list-jobs, and restart any single_node deployments afterward.
Ensure the command runs with the same environment configuration (database, object storage, root user) as your running cluster, since the binary reads its configuration the same way the server does.