Client CLI Reference

The stowry-cli is a command-line client for interacting with Stowry servers. It provides a simple interface for uploading, downloading, listing, and deleting objects without writing code.

Overview

Stowry provides two separate binaries:

Binary	Purpose
`stowry`	Server-side CLI for running and managing the Stowry server
`stowry-cli`	Client-side CLI for interacting with a running Stowry server

Server Mode Awareness

Commands behave differently depending on the server’s mode:

Command	Store Mode	Static Mode	SPA Mode
`upload`	Works	Works	Works
`download`	Returns file or 404	Returns file, tries `path/index.html`, or 404	Returns file or falls back to `/index.html`
`delete`	Works	Works	Works
`list`	Works	404 error	404 error

Installation

Binary Download

Download pre-built binaries from the GitHub Releases page.

Linux

# amd64
curl -LO https://github.com/sagarc03/stowry/releases/latest/download/stowry-cli_VERSION_linux_amd64.tar.gz
tar xzf stowry-cli_VERSION_linux_amd64.tar.gz
sudo mv stowry-cli /usr/local/bin/

# arm64
curl -LO https://github.com/sagarc03/stowry/releases/latest/download/stowry-cli_VERSION_linux_arm64.tar.gz
tar xzf stowry-cli_VERSION_linux_arm64.tar.gz
sudo mv stowry-cli /usr/local/bin/

Replace VERSION with the desired version (e.g., 1.0.0). Check the releases page for available versions.

macOS

# Apple Silicon (M1/M2/M3)
curl -LO https://github.com/sagarc03/stowry/releases/latest/download/stowry-cli_VERSION_darwin_arm64.tar.gz
tar xzf stowry-cli_VERSION_darwin_arm64.tar.gz
sudo mv stowry-cli /usr/local/bin/

# Intel
curl -LO https://github.com/sagarc03/stowry/releases/latest/download/stowry-cli_VERSION_darwin_amd64.tar.gz
tar xzf stowry-cli_VERSION_darwin_amd64.tar.gz
sudo mv stowry-cli /usr/local/bin/

Windows

Download stowry-cli_VERSION_windows_amd64.zip from the releases page, extract the archive, and add the binary to your PATH.

Build from Source

go install github.com/sagarc03/stowry/cmd/stowry-cli@latest

Configuration

The client supports multiple server profiles, allowing you to easily switch between different Stowry servers.

Configuration Priority

Settings are resolved in this order (highest to lowest priority):

Command-line flags (--endpoint, --access-key, --secret-key)
Environment variables (STOWRY_ENDPOINT, STOWRY_ACCESS_KEY, STOWRY_SECRET_KEY)
Selected profile (--profile flag or STOWRY_PROFILE env var)
Default profile from config file

Configuration File

Create ~/.stowry/config.yaml with one or more profiles:

profiles:
  - name: local
    endpoint: http://localhost:5708
    access_key: YOUR_LOCAL_ACCESS_KEY
    secret_key: YOUR_LOCAL_SECRET_KEY
    default: true

  - name: production
    endpoint: https://storage.example.com
    access_key: YOUR_PROD_ACCESS_KEY
    secret_key: YOUR_PROD_SECRET_KEY

  - name: staging
    endpoint: https://staging.example.com
    access_key: YOUR_STAGING_ACCESS_KEY
    secret_key: YOUR_STAGING_SECRET_KEY

The first profile is used as default, unless one is marked with default: true.

Using Profiles

# Uses default profile
stowry-cli upload ./file.txt

# Use a specific profile
stowry-cli --profile production upload ./file.txt
stowry-cli -p staging list

# Set profile via environment variable
export STOWRY_PROFILE=production
stowry-cli upload ./file.txt

Environment Variables

export STOWRY_PROFILE=production            # Select profile by name
export STOWRY_CONFIG=~/.stowry/config.yaml  # Custom config file path
export STOWRY_ENDPOINT=http://localhost:5708 # Override server URL
export STOWRY_ACCESS_KEY=YOUR_ACCESS_KEY    # Override access key
export STOWRY_SECRET_KEY=YOUR_SECRET_KEY    # Override secret key

Command-line Overrides

Flags override both profile and environment settings:

stowry-cli --profile production --endpoint https://backup.example.com upload ./file.txt

Global Flags

These flags are available for all commands:

Flag	Short	Env Var	Default	Description
`--config`	`-c`	`STOWRY_CONFIG`	`~/.stowry/config.yaml`	Config file path
`--profile`	`-p`	`STOWRY_PROFILE`	-	Use named profile from config
`--endpoint`	`-e`	`STOWRY_ENDPOINT`	`http://localhost:5708`	Endpoint URL override
`--access-key`	`-a`	`STOWRY_ACCESS_KEY`	-	Access key override
`--secret-key`	`-k`	`STOWRY_SECRET_KEY`	-	Secret key override
`--json`	-	-	`false`	Output results as JSON
`--quiet`	`-q`	-	`false`	Suppress non-essential output
`--help`	`-h`	-	-	Help for the command

Commands

configure

Manage server profiles in the configuration file.

stowry-cli configure <subcommand>

Subcommands:

Subcommand	Description
`list`	List all configured profiles
`add <name>`	Add a new profile interactively
`update <name>`	Update an existing profile interactively
`remove <name>`	Remove a profile
`set-default <name>`	Set the default profile
`show [name]`	Show profile details (default profile if name omitted)

Flags for add and update:

Flag	Default	Description
`--skip-test`	`false`	Skip connection test before saving

Examples:

# List all profiles (* marks default)
stowry-cli configure list

# Add a new profile interactively
stowry-cli configure add production

# Add profile without testing connection
stowry-cli configure add staging --skip-test

# Update an existing profile
stowry-cli configure update production

# Update profile without testing connection
stowry-cli configure update production --skip-test

# Show profile details (secrets hidden)
stowry-cli configure show production

# Show profile with secrets revealed
stowry-cli configure show production --show-secrets

# Set default profile
stowry-cli configure set-default production

# Remove a profile
stowry-cli configure remove old-server

Output of configure list:

  NAME        ENDPOINT                     ACCESS KEY
  ----------  ---------------------------  --------------------
* local       http://localhost:5708        AKIA...MPLE
  production  https://storage.example.com  PROD...KEY

upload

Upload files to the server.

stowry-cli upload [flags] <local-path> [remote-path]

If remote-path is omitted, the local path is used (normalized):

./foo/bar.txt → foo/bar.txt
/abs/path/file.txt → abs/path/file.txt
../sibling/file.txt → sibling/file.txt

Flags:

Flag	Short	Default	Description
`--recursive`	`-r`	`false`	Upload directory recursively
`--content-type`	`-t`	auto-detect	Override content type

Examples:

# Upload using local path as remote path
stowry-cli upload ./document.pdf

# Upload nested file (preserves directory structure)
stowry-cli upload ./images/photo.jpg

# Upload with explicit remote path
stowry-cli upload ./document.pdf reports/2024/report.pdf

# Upload with explicit content type
stowry-cli upload --content-type application/json ./data.json

# Upload a directory recursively
stowry-cli upload -r ./images/

# Upload directory to different remote prefix
stowry-cli upload -r ./local/images/ remote/media/

# Upload with JSON output
stowry-cli upload --json ./file.txt

Output:

uploaded path/file.txt (1234 bytes)

With --json:

[
  {
    "local_path": "./file.txt",
    "remote_path": "path/file.txt",
    "size": 1234,
    "content_type": "text/plain"
  }
]

download

Download a file from the server.

stowry-cli download [flags] <remote-path> [local-path]

Flags:

Flag	Short	Default	Description
`--output`	`-o`	-	Output file path
`--stdout`	-	`false`	Write content to stdout

Examples:

# Download to current directory (uses remote filename)
stowry-cli download path/file.txt

# Download to specific local path
stowry-cli download path/file.txt ./local-copy.txt

# Download using --output flag
stowry-cli download -o ./local-copy.txt path/file.txt

# Pipe to another command
stowry-cli download --stdout config.json | jq .

# Download with JSON metadata output
stowry-cli download --json path/file.txt

Output:

downloaded path/file.txt -> ./file.txt (1234 bytes)

With --stdout, the file content is written directly to stdout, making it easy to pipe to other commands.

delete

Delete one or more files from the server.

stowry-cli delete [flags] <remote-path> [remote-path...]

Examples:

# Delete a single file
stowry-cli delete path/file.txt

# Delete multiple files
stowry-cli delete old/a.txt old/b.txt old/c.txt

# Delete with quiet mode
stowry-cli delete -q temp/file.txt

# Delete with JSON output
stowry-cli delete --json path/file.txt

Output:

deleted path/file.txt

With --json:

[
  {
    "path": "path/file.txt",
    "deleted": true
  }
]

list

List objects on the server.

stowry-cli list [flags] [prefix]

Note: This command only works when the server is running in store mode. In static or spa modes, this will return a 404 error.

Flags:

Flag	Short	Default	Description
`--prefix`	-	-	Filter by path prefix
`--limit`	`-l`	`100`	Maximum results per page (max: 1000)
`--all`	-	`false`	Fetch all pages
`--cursor`	-	-	Pagination cursor for next page

Examples:

# List all objects
stowry-cli list

# List with prefix (positional argument)
stowry-cli list images/

# List with prefix (flag)
stowry-cli list --prefix documents/

# Limit results
stowry-cli list --limit 10

# Fetch all pages
stowry-cli list --all

# Continue from cursor
stowry-cli list --cursor "eyJwYXRoIjoi..."

# JSON output
stowry-cli list --json --prefix images/

Output:

images/photo1.jpg    image/jpeg    102400    2024-01-15T10:00:00Z
images/photo2.jpg    image/jpeg    204800    2024-01-15T11:00:00Z
images/photo3.jpg    image/jpeg    153600    2024-01-15T12:00:00Z

Next cursor: eyJwYXRoIjoi...

With --json:

{
  "items": [
    {
      "path": "images/photo1.jpg",
      "content_type": "image/jpeg",
      "file_size_bytes": 102400,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ],
  "next_cursor": "eyJwYXRoIjoi..."
}

Exit Codes

Code	Meaning
0	Success
1	Error (authentication failed, file not found, server error, etc.)

Examples

Basic Workflow

# Configure credentials
export STOWRY_ENDPOINT=http://localhost:5708
export STOWRY_ACCESS_KEY=your-access-key
export STOWRY_SECRET_KEY=your-secret-key

# Upload a file (uses local path as remote path)
stowry-cli upload ./documents/report.pdf

# Upload with explicit remote path
stowry-cli upload ./report.pdf documents/2024/report.pdf

# List files
stowry-cli list documents/

# Download a file
stowry-cli download documents/report.pdf ./downloaded-report.pdf

# Delete when done
stowry-cli delete documents/report.pdf

Batch Operations

# Upload entire directory (preserves structure)
stowry-cli upload -r ./website/

# Upload directory to different prefix
stowry-cli upload -r ./website/ static/

# Delete multiple files
stowry-cli delete static/old1.html static/old2.html static/old3.html

Scripting with JSON Output

# Get file count
stowry-cli list --json --all | jq '.items | length'

# Get total size
stowry-cli list --json --all | jq '[.items[].file_size_bytes] | add'

# Filter by content type
stowry-cli list --json --all | jq '.items[] | select(.content_type == "image/jpeg")'

Using Profiles

# Set up profiles interactively
stowry-cli configure add local
stowry-cli configure add production
stowry-cli configure add staging

# Set production as default
stowry-cli configure set-default production

# Use default profile (production)
stowry-cli upload ./file.txt

# Use specific profile
stowry-cli -p staging upload ./file.txt

# CI/CD: Set profile via environment
export STOWRY_PROFILE=production
stowry-cli upload ./dist/

Client CLI Reference

Client CLI Reference

Overview

Server Mode Awareness

Installation

Binary Download

Linux

macOS

Windows

Build from Source

Configuration

Configuration Priority

Configuration File

Using Profiles

Environment Variables

Command-line Overrides

Global Flags

Commands

configure

upload

download

delete

list

Exit Codes

Examples

Basic Workflow

Batch Operations

Scripting with JSON Output

Using Profiles

See Also