RawbackRawback
Back to Rawback CLI

Rawback CLI documentation

CLI guide

From installation and sign-in to resumable uploads, library management, and structured automation for scripts and AI agents.

Install

Rawback ships as a standalone binary for Linux, macOS, and Windows on x86-64 and arm64. It does not require Node.js or Bun once installed.

macOS with Homebrew

Install the signed and notarized macOS binary from Rawback's Homebrew tap:

Shell
brew install --cask rawback-app/tap/rawback

Upgrade it later with brew upgrade --cask rawback-app/tap/rawback.

Linux and macOS installer

The installer selects the correct release for your operating system and CPU, verifies its SHA-256 checksum, and installs it into ~/.local/bin:

Shell
curl -fsSL https://raw.githubusercontent.com/rawback-app/cli/main/install.sh | sh

The installer never edits your shell startup files. If ~/.local/bin is not already on PATH, add it yourself. You can also choose another user-owned directory:

Shell
curl -fsSL https://raw.githubusercontent.com/rawback-app/cli/main/install.sh | \
  RAWBACK_INSTALL_DIR="$HOME/bin" sh

Windows PowerShell

Run the PowerShell installer to place rawback.exe in $HOME\.local\bin:

PowerShell
irm https://raw.githubusercontent.com/rawback-app/cli/main/install.ps1 | iex

Set $env:RAWBACK_INSTALL_DIR first if you prefer another directory. The installer warns when the destination is not on PATH.

Manual installation

Download the archive for your operating system and CPU, along with checksums.txt, from the GitHub releases page. Verify the archive, extract rawback (rawback.exe on Windows), and move it to a directory on PATH.

Windows binaries are not currently Authenticode-signed. macOS binaries are Developer ID-signed and notarized.

Verify the install

Shell
rawback --version
rawback --help

Quick start

1. Sign in

Shell
rawback auth
rawback auth status

rawback auth securely prompts for your email and password. Access and refresh tokens are stored in ~/.rawback/credentials.json, and expired access tokens are refreshed automatically when possible.

2. Explore your account

Once authenticated, these commands give you a quick view of your Rawback library:

Shell
rawback photos list
rawback dream list
rawback album list
rawback shares list
rawback uploads
rawback usage
rawback pricing
rawback web

Use context-specific help whenever you need to discover options without leaving the terminal:

Shell
rawback photos list --help
rawback album article --help
rawback shares list --help

Upload photos

CLI uploads use an SFTP credential tied to your Rawback account. Create one first; its generated password is displayed only once, so save it before continuing.

Shell
rawback cred add --name "My computer"

Create ~/.rawback/config.yml with the account slug shown by rawback auth status and the generated password:

YAML
sftp:
  endpoint: sftp://ftp.rawback.app:2222
  username: your-account-slug
  password: 'generated-password'

On Linux and macOS, protect the configuration because it contains a password:

Shell
chmod 600 ~/.rawback/config.yml

Preview the work before transferring anything, then run the upload:

Shell
rawback photos upload --path ~/Pictures/Export --dry-run
rawback photos upload --path ~/Pictures/Export

Directories are scanned recursively. You can increase parallel transfers when your network and server can sustain them:

Shell
rawback photos upload --path ./photos --concurrency 8

Interrupted uploads resume safely using local progress state, and files already uploaded are skipped. Symbolic links and unsupported files are ignored; a selection containing no supported images fails without starting a transfer.

Supported image formats include JPEG, PNG, WebP, GIF, TIFF, HEIC/HEIF, BMP, and AVIF. Supported RAW formats include CR2, CR3, NEF, ARW, DNG, RAF, ORF, PEF, RW2, SRW, and X3F.

Common workflows

Search and filter photos

Search filenames and metadata, combine filters, or limit results to a capture window:

Shell
rawback photos list --search "Iceland"
rawback photos list --camera-make Sony --rate 4,5 --has-gps
rawback photos list \
  --captured-after 2026-01-01 \
  --captured-before 2026-02-01

Build albums and publish stories

Shell
rawback album create --name "Iceland" --permission private
rawback album view 42
rawback album image add 42 108
rawback album article edit 42 \
  --title "Iceland in winter" \
  --content-file story.md
rawback album article publish 42

Album articles accept Markdown from a file, which makes longer stories easy to edit, review, and version locally.

Review dreams, shares, and uploads

Shell
# Inspect an AI-generated daily recap
rawback dream list
rawback dream get 42
rawback dream retry 42

# Browse incoming shares and manage an outgoing link
rawback shares list --scope with-me --type photo
rawback shares list --kind link --access restricted --expiry valid
rawback shares recipients 7
rawback shares link 7 --copy
rawback shares disable 7

# Find failed transfer sessions
rawback uploads --status failed

Credential management is available under both rawback credentials and its shorter rawback cred alias:

Shell
rawback cred list
rawback cred add --name "Home workstation"
rawback cred del 7

Automation and JSON output

Add --json to data-oriented commands for structured, undecorated output designed for scripts and AI agents:

Shell
rawback photos list --page-size 10 --json
rawback dream get 42 --json
rawback shares list --scope with-me --type album --json
rawback usage --json

Redirected human-facing output stays line-oriented and omits cursor-control sequences. JSON output, article --content-only, and --version remain undecorated whether output is interactive or redirected.

Use the command's exit status to detect failures. Keep agent calls bounded with explicit pagination and filters. Destructive operations require confirmation in an interactive terminal; commands that expose --force can be made non-interactive only when you explicitly opt in.

Files and security

Rawback keeps CLI state in ~/.rawback/:

| File | Purpose | | ------------------------ | --------------------------------------------------- | | credentials.json | Access and refresh tokens created by rawback auth | | config.yml | Optional API/web hosts and SFTP upload settings | | upload-progress.sqlite | Resume history and trusted SFTP host keys |

Credential and upload-state files are created with restrictive permissions on Unix. Because you create config.yml yourself, upload commands require mode 0600 on Unix. Never commit this directory or paste its secrets into issues, logs, or automation output.

Keep exploring