CLI Quickstart

The Sairo CLI brings indexed search and listing to your terminal. Instead of enumerating S3 objects live on every command (like mc or aws s3), it queries Sairo’s pre-built SQLite FTS5 index — returning results in milliseconds regardless of bucket size.

Installation

Homebrew

brew install ashwathstephen/sairo/sairo

Go Install

go install github.com/ashwathstephen/sairo/cli@latest

Binary Download

Download the latest release from GitHub Releases for your platform:

• macOS (ARM): sairo_*_darwin_arm64.tar.gz
• macOS (Intel): sairo_*_darwin_amd64.tar.gz
• Linux (AMD64): sairo_*_linux_amd64.tar.gz
• Linux (ARM64): sairo_*_linux_arm64.tar.gz
• Windows: sairo_*_windows_amd64.zip

Extract and move to your PATH:

tar xzf sairo_*_darwin_arm64.tar.gz
sudo mv sairo /usr/local/bin/

Verify installation:

sairo version

Login

1. Connect to your Sairo instance:

   sairo login https://sairo.example.com

   Enter your username and password when prompted. If 2FA is enabled, you’ll be asked for your TOTP code.

2. Verify the connection:

   sairo status

     Profile:    production
     Server:     https://sairo.example.com
     User:       admin (admin)
     Session:    expires in 23h 14m
     Version:    2.0.0
     S3:         https://s3.amazonaws.com (connected, 12ms)
   
     BUCKETS     OBJECTS     TOTAL SIZE    LAST CRAWL
     ───────     ───────     ──────────    ──────────
     4           134,707     38.2 TB       2m ago

Tip

Credentials are stored in your OS keyring (macOS Keychain, Linux libsecret, Windows Credential Manager) — never in plaintext config files.

Core Commands

List buckets and objects

# List all buckets
sairo ls

# List objects in a bucket
sairo ls my-bucket/logs/ -l

# Recursive listing (all objects under a prefix)
sairo ls my-bucket/data/ -r --sort size

Search (indexed full-text search)

# Search across a bucket — returns in milliseconds
sairo search my-bucket "parquet"

# Search within a specific prefix
sairo search my-bucket "config" --prefix settings/

Download and upload

# Download a file
sairo get my-bucket/reports/summary.pdf ./

# Upload a file
sairo put ./data.csv my-bucket/uploads/

# Recursive download
sairo get my-bucket/exports/ ./local-dir/ -r

Storage analytics

# Disk usage breakdown
sairo du my-bucket -d 1

# Object metadata
sairo info my-bucket/data/events.parquet

# Directory tree
sairo tree my-bucket/logs/ -d 2 --size

File operations

# Preview file contents
sairo cat my-bucket/config/app.yaml

# Generate a presigned URL
sairo presign my-bucket/reports/summary.pdf --expires 86400

# Server-side copy
sairo cp my-bucket/a.txt my-bucket/b.txt

# Delete with confirmation
sairo rm my-bucket/old-data/ -r

JSON Output

Every command supports --json for machine-readable output. JSON mode is auto-enabled when stdout is piped.

# Explicit JSON
sairo ls my-bucket/ --json | jq '.files[] | .key'

# Auto-detected (pipe)
sairo search my-bucket "parquet" | jq .

Multiple Profiles

Manage connections to multiple Sairo instances:

# Login with a named profile
sairo login https://staging.example.com --profile staging

# Use a specific profile
sairo ls my-bucket/ --profile staging

# Switch default profile
sairo login https://production.example.com --profile production

API Token Authentication

For CI/CD pipelines, use API tokens instead of interactive login:

# Login with a token
sairo login https://sairo.example.com --token sairo_abc123...

# Or use an environment variable
export SAIRO_TOKEN=sairo_abc123...
sairo ls my-bucket/

Performance

The CLI queries Sairo’s indexed backend, not S3 directly. On a production bucket with 134K+ objects:

Operation	mc / aws s3	sairo	Speedup
List top-level folder	~3 min	0.05s	3,000x+
Recursive list (134K objects)	~12 min	4.8s	150x
Search by filename	3+ min	0.08s	2,000x+
Storage breakdown	3+ min	0.03s	6,000x+

Next Steps

• Command Reference — All 24 commands with flags and examples
• Benchmarks — Full performance data
• API Reference — The REST API the CLI talks to