atlas search

file version: 10 July 2026

Overview

Search for files by metadata using table.column syntax. Fields are auto-discovered from the query engine. Use help search in the shell for available tables and columns.

Operators: =, !=, >, >=, <, <=, =~ (regex)

Boolean: AND OR ( )

Size: B, KB, MB, GB, TB

Time: ISO 8601, N days ago, yesterday

Grouping with parentheses is supported:

(scoutfs.path =~ users OR scoutfs.path =~ projects) AND netcdf.institution =~ 'GFDL'

Usage

atlas search <query> [flags]

Query Help

Use expressions to combine metadata filters. The exact syntax supports boolean combinations and field-specific comparisons.

Command Flags

Flag	Description
--resource strings	Limit search to specific resource(s)
--limit int	Maximum number of results (default 1000, 0 = unlimited for admins)
--offset int	Result offset for pagination (default 0)
--timeout duration	Admin: extend the 30s search deadline (e.g. 5m, 1h); ignored for non-admins
--skip-count	Skip the COUNT(*) query; total_count reflects only the returned page
--skip-sort	Skip the ORDER BY path clause; results come back unordered (faster)
--batch int	Rows per streaming gRPC batch (default 5000, 10-100000); --limit 0 only

Examples

atlas search "images.f_number >= 4 AND images.iso >= 800"
atlas search "scoutfs.path =~ \".*\.tiff$\""
atlas search "scoutfs.size >= 1GB AND scoutfs.mod_time > 2024-01-01"
atlas search "documents.author = alice AND documents.page_count > 10"
atlas search "(scoutfs.path =~ users OR scoutfs.path =~ projects) AND netcdf.institution =~ GFDL"

Global Flags

Flag	Description
--ca-cert string	Path to CA certificate for server verification
--format string	Machine-readable output format (json or csv); omit for the default human-readable output
-L, --lang string	Interface language (en, de)
--no-color	Disable color output
-P, --plaintext	Use plaintext (non-TLS) connection
-s, --server string	ATLAS server address; defaults to ACLI_SERVER, then the stored session, /etc/atlas/atlas.conf, and finally localhost:7449
--tls-skip-verify	Skip TLS certificate verification; enabled by default for self-signed setups