Command Reference

Global Flags

Every command accepts these flags:

Flag	Short	Default	Description
--json	-j	false	Output as JSON (auto-enabled when stdout is not a TTY)
--profile	-p	from config	Use a specific login profile
--endpoint	-e	from profile	Route through a specific S3 endpoint
--quiet	-q	false	Suppress non-essential output
--no-color		false	Disable colored output
--debug		false	Print HTTP request/response details

Session Commands

sairo login [url]

Authenticate with a Sairo instance.

# Interactive login
sairo login https://sairo.example.com

# API token (for CI/CD)
sairo login https://sairo.example.com --token sairo_abc123...

# Named profile
sairo login https://staging.example.com --profile staging

Flag	Description
--token <string>	Use an API token instead of username/password
--profile <name>	Save as named profile

sairo logout

Clear stored credentials.

sairo logout             # Current profile
sairo logout --all       # All profiles

sairo status

Show session info, server health, and bucket summary.

sairo status
sairo status --json

---

Indexed Read Commands

These commands query Sairo’s SQLite FTS5 index — results return in milliseconds regardless of bucket size.

sairo ls [bucket[/prefix]]

List buckets, folders, or objects.

sairo ls                                    # All buckets
sairo ls my-bucket/                         # Top-level objects
sairo ls my-bucket/logs/ -l                 # Long format (size, date)
sairo ls my-bucket/data/ -r --sort size     # Recursive, sorted by size
sairo ls my-bucket/ --fresh                 # Bypass index, query S3 directly

Flag	Short	Default	Description
--long	-l	false	Show size and date
--recursive	-r	false	List all objects under prefix
--sort	-s	name	Sort by: name, size, date
--reverse		false	Reverse sort order
--fresh		false	Bypass index, query S3 directly
--limit	-n	0	Limit results (0 = unlimited)

sairo search <bucket> <query>

Full-text search across indexed object keys.

sairo search my-bucket "parquet"
sairo search my-bucket "config" --prefix settings/ -l
sairo search my-bucket "2026-03" --limit 50

Flag	Short	Default	Description
--prefix		""	Restrict search to a prefix
--limit	-n	200	Maximum results
--long	-l	false	Show size and date

sairo du [bucket[/prefix]]

Show disk usage (like du -sh), using pre-computed index stats.

sairo du my-bucket -d 1
sairo du my-bucket/logs/ --sort size --top 10

Flag	Short	Default	Description
--depth	-d	1	Folder depth for breakdown
--sort	-s	size	Sort by: size, name, count
--top	-n	0	Show only top N entries

sairo info <bucket>/<key>

Show detailed object metadata. For Parquet/ORC/Avro files, includes schema info.

sairo info my-bucket/data/events.parquet
sairo info my-bucket/config/app.yaml

sairo tree <bucket[/prefix]>

Display directory tree structure.

sairo tree my-bucket/logs/ -d 2 --size
sairo tree my-bucket/ --dirs-only

Flag	Short	Default	Description
--depth	-d	3	Max depth to display
--dirs-only		false	Only show directories
--size		false	Show folder sizes

---

File Operations

sairo get <bucket>/<key> [local-path]

Download objects with progress display.

sairo get my-bucket/report.pdf ./
sairo get my-bucket/exports/ ./local/ -r --parallel 8
sairo get my-bucket/config.yaml ./config.yaml --version abc123

Flag	Short	Default	Description
--recursive	-r	false	Download all objects under prefix
--version	-v	""	Download a specific version
--parallel		4	Concurrent downloads (recursive)
--overwrite		false	Overwrite existing files
--dry-run		false	Show what would be downloaded

sairo put <local-path> <bucket>[/prefix]

Upload files with progress display.

sairo put ./data.csv my-bucket/uploads/
sairo put ./reports/ my-bucket/reports/2026/ -r

Flag	Short	Default	Description
--recursive	-r	false	Upload directory contents
--parallel		4	Concurrent uploads
--dry-run		false	Show what would be uploaded
--exclude		""	Glob pattern to exclude

sairo cp <src> <dst>

Server-side copy (no download).

sairo cp my-bucket/a.txt my-bucket/b.txt
sairo cp my-bucket/data/ other-bucket/data/ -r

Flag	Short	Default	Description
--recursive	-r	false	Copy all objects under prefix

sairo mv <src> <dst>

Rename or move objects (server-side copy + delete).

sairo mv my-bucket/old-name.log my-bucket/new-name.log

sairo rm <bucket>/<key>

Delete objects with safety confirmation.

sairo rm my-bucket/temp/file.txt
sairo rm my-bucket/old-data/ -r -f
sairo rm my-bucket/archive/ -r --purge-versions --force

Flag	Short	Default	Description
--recursive	-r	false	Delete all objects under prefix
--force	-f	false	Skip confirmation
--purge-versions		false	Also delete all old versions
--dry-run		false	Show what would be deleted

sairo cat <bucket>/<key>

Print object contents to stdout.

sairo cat my-bucket/config/app.yaml
sairo cat my-bucket/logs/app.log --tail 1000 | grep ERROR

Flag	Default	Description
--head	0	Show first N bytes
--tail	0	Show last N bytes
--max	5MB	Max bytes to fetch

sairo presign <bucket>/<key>

Generate a presigned URL for sharing.

sairo presign my-bucket/report.pdf --expires 86400

Flag	Short	Default	Description
--expires		3600	Expiry in seconds (60-604800)
--version	-v	""	Presign a specific version

---

Versioning Commands

sairo versions <bucket>/<key>

List all versions of an object.

sairo versions my-bucket/config/app.yaml

sairo restore <bucket>/<key> --version <id>

Restore a previous version as latest.

sairo restore my-bucket/config/app.yaml --version abc123

Flag	Short	Description
--version	-v	Version ID to restore (required)

sairo purge <bucket>/<key-or-prefix>

Permanently delete all versions and delete markers.

sairo purge my-bucket/old-file.txt --force
sairo purge my-bucket/old-data/ -r --force

Flag	Short	Default	Description
--force	-f	false	Skip confirmation
--recursive	-r	false	Purge all objects under prefix

---

Bucket Configuration

sairo versioning <bucket> [enable|suspend|status]

sairo versioning my-bucket              # Show status
sairo versioning my-bucket enable       # Enable versioning
sairo versioning my-bucket suspend      # Suspend versioning

sairo lifecycle <bucket> [get|set|delete]

sairo lifecycle my-bucket               # Show rules
sairo lifecycle my-bucket set --file rules.json
sairo lifecycle my-bucket delete

Flag	Default	Description
--file	""	JSON file containing lifecycle rules (for set)

sairo tags <bucket>[/<key>] [get|set|delete]

sairo tags my-bucket                              # Bucket tags
sairo tags my-bucket/file.txt                     # Object tags
sairo tags my-bucket set env=production team=data # Set bucket tags
sairo tags my-bucket/file.txt delete              # Remove object tags

sairo mb <bucket> / sairo rb <bucket>

Create or remove buckets.

sairo mb new-bucket
sairo rb old-bucket --force

Flag	Short	Description
--force	-f	(rb only) Skip confirmation

---

Live Operations

sairo watch <bucket>[/prefix]

Watch for changes in real-time (polls at an interval, diffs against previous state).

sairo watch my-bucket/logs/ -i 30

Flag	Short	Default	Description
--interval	-i	30	Poll interval in seconds
--filter	-f	""	Glob pattern to filter

sairo diff <bucket>/<prefix>

Show what changed in a prefix over a time period.

sairo diff my-bucket/logs/ --since 24h
sairo diff my-bucket/data/ --since 7d --type added

Flag	Short	Default	Description
--since	-s	24h	Time window (1h, 7d, 30d)
--type	-t	all	Filter: added, removed, modified

---

Utility Commands

sairo version

Print the CLI version, commit hash, and build date.

sairo version
sairo version --json

---

Exit Codes

Code	Meaning
0	Success
1	General error
2	Authentication error
3	Permission denied
4	Not found
5	User cancelled

Credential Storage

OS	Backend
macOS	Keychain
Linux	libsecret (GNOME Keyring / KWallet)
Windows	Credential Manager

Fallback: ~/.config/sairo/credentials with 0600 permissions (when no keyring is available).

Environment variable: SAIRO_TOKEN for CI/CD use.