Use Rawback (出片 in Chinese) from a terminal or an automation script. The CLI can sign in to your account, upload photo and RAW files, search your library, manage albums and their Markdown articles, inspect usage, and open your profile in a browser.
- Upload a file or recursively upload a directory over SFTP.
- Safely resume an interrupted upload and skip exact files already uploaded.
- Check which local photo and RAW files are already in your Rawback library.
- Find photos by describing them — "from 2012, all images in NYC" — or by metadata, capture date, rating, location, and GPS data.
- Create and curate albums, smart filters, cover images, tags, and Markdown stories.
- List and inspect daily AI-generated dream recaps, including their contributing photos.
- Browse content shared with you and manage your outgoing share links.
- Control a Canon camera over CCAPI: shoot, change settings, browse and download the card, and stream live view.
- Manage the SFTP credentials associated with your account.
- Inspect the shared local configuration without exposing its SFTP password.
- Inspect upload sessions, storage usage, AI credits, and pricing.
- Request machine-readable JSON from read and credential commands.
On Linux and macOS, download the matching release, verify its SHA-256 checksum,
and install it into ~/.local/bin:
curl -fsSL https://raw.githubusercontent.com/rawback-app/cli/main/install.sh | shThe installer does not edit shell startup files. If ~/.local/bin is not on
PATH, add it yourself. To choose another user-owned directory:
curl -fsSL https://raw.githubusercontent.com/rawback-app/cli/main/install.sh | \
RAWBACK_INSTALL_DIR="$HOME/bin" shOn Windows, run the PowerShell installer:
irm https://raw.githubusercontent.com/rawback-app/cli/main/install.ps1 | iexIt installs to $HOME\.local\bin and warns if that directory is not on
PATH. Set $env:RAWBACK_INSTALL_DIR before running it to select another
directory.
On macOS, install the signed and notarized binary from the Rawback tap:
brew install --cask rawback-app/tap/rawbackUpgrade it later with brew upgrade --cask rawback-app/tap/rawback.
Download the archive for your operating system and CPU, plus checksums.txt,
from GitHub Releases. Verify the
archive, extract rawback (rawback.exe on Windows), and put it on PATH.
Once installed, view the available commands with:
rawback --helpRelease archives are available for Linux, macOS, and Windows on both x86-64 and
arm64. The standalone binary does not require Bun. macOS binaries are Developer
ID-signed and notarized, including the bundled ffmpeg and ffprobe helpers;
Windows binaries are not currently Authenticode-signed.
Bun 1.4.0 is required:
git clone https://github.com/rawback-app/cli.git
cd cli
bun install --frozen-lockfile
bun run build
./dist/rawback --versionMove dist/rawback somewhere on your PATH if you want to run it outside the
repository.
To cross-compile every release target locally, install GoReleaser 2.17 and run:
bun run build:allrawback auth
rawback auth statusrawback auth creates a 10-minute device session, prints a copyable approval
link, and opens it in your browser. Sign in on the web if needed, review the CLI
request details, and authorize it. The resulting access and refresh tokens are
saved in ~/.rawback/credentials.json. Expired access tokens are refreshed
automatically when possible. Temporary device-session creation failures are
retried before the command reports an error with a support trace ID when
available. Persistent device-authentication failures also include the raw server
error for diagnosis.
If you also run a local Rawback server, define it once in
~/.rawback/config.yml and sign into both — they stay signed in side by side:
current: production
environments:
production:
apiHost: https://api.rawback.app
webHost: https://rawback.app
local:
apiHost: http://localhost:23164
webHost: http://localhost:3407rawback --env local auth # sign in without touching production
rawback config env list # names, hosts, and which are signed in
rawback config use local # make it the default for later commandsSee docs/configuration.md for the full format.
These commands work immediately after sign-in:
rawback photos list
rawback dream list
rawback album list
rawback shares list
rawback uploads
rawback usage
rawback usage --detail
rawback pricing
rawback config view
rawback webAdd --json to data-oriented commands when you need structured output:
rawback photos list --page-size 10 --json
rawback dream get 42 --json
rawback shares list --scope with-me --type album --json
rawback usage --json
rawback config view --jsonHuman-facing output uses a compact terminal UI with responsive columns, quota
meters, charts, status notices, and activity indicators. During uploads, an interactive terminal shows
aggregate progress, transfer speed, ETA, and the active files. Redirected output
stays line-oriented and does not contain cursor-control sequences. --json,
article --content-only, and --version remain undecorated for scripts and
other tools.
Create an SFTP credential. Its password is displayed only once, so save it before continuing:
rawback cred add --name "My computer"Open ~/.rawback/config.yml — the CLI created it on your first command — and
uncomment its sftp: block, filling in the account slug shown by
rawback auth status and the generated password:
sftp:
endpoint: sftp://ftp.rawback.app:23168
username: your-account-slug
password: 'generated-password'The file was created at mode 0600 on Linux and macOS because it holds that
password. If you replaced it by hand or copied it from another machine, restore
the permissions:
chmod 600 ~/.rawback/config.ymlInspect the stored file without exposing sftp.password:
rawback config view
rawback config view --jsonThe viewer does not apply environment overrides or built-in defaults. It prints
[REDACTED] in place of the stored SFTP password.
Local metadata parsing is sized automatically from the machine's CPU and memory. To test an exact worker count, add an integer from 1 through 64; omit this block to keep the recommended automatic behavior:
metadata:
concurrency: 8This setting affects photos check and the metadata stage of photos upload.
The upload command's --concurrency option controls SFTP transfers separately.
Preview an upload, then run it:
rawback photos check --path ~/Pictures/Export
rawback photos upload --path ~/Pictures/Export --dry-run
rawback photos upload --path ~/Pictures/ExportDirectories are scanned recursively. Symbolic links and unsupported files are skipped; the command fails if the selected path contains no supported files. Before SFTP transfer, the CLI reads capture metadata locally and skips a photo only when both its filename and capture time match an existing Rawback image. Files without usable capture metadata continue through normal SFTP verification. Supported image formats are JPEG/JPG, PNG, WebP, GIF, TIFF, HEIC/HEIF, BMP, and AVIF. Supported RAW formats are CR2, CR3, NEF, ARW, DNG, RAF, ORF, PEF, RW2, SRW, and X3F.
photos check reports every supported local file as already in Rawback, not in
Rawback, or unknown. Add --json for a machine-readable report. A file is an
exact match when its filename and locally extracted EXIF capture time match an
image in the authenticated library; this is not a byte-content comparison.
In an interactive terminal, the command shows live progress while scanning
files, reading photo metadata, and checking Rawback. Redirected and JSON output
remain undecorated.
For host-key pinning, resumable-upload behavior, and troubleshooting, see Configuration and uploads.
Videos upload directly to storage instead of over SFTP, so they do not share the photo upload pipeline:
rawback videos list
rawback videos upload --file ~/Movies/hike.mp4
rawback videos upload --file ~/Movies/hike.mp4 --thumbnail ~/Pictures/poster.jpg
rawback videos repair --id 7 --file ~/Movies/hike.mp4
rawback videos update --id 7 --title "Hike, day two"
rawback videos delete --id 7Supported containers are MP4, M4V, MOV, WebM, MKV, AVI, MPEG, 3GP, and TS, up
to 100 GB. The file is sent in parts to presigned URLs and read from disk on
demand. Before upload, FFmpeg tools extract a poster and audio for transcription. Pass --thumbnail to use a JPEG,
PNG, or WebP poster, or --no-transcript to skip audio extraction. Video parts
are read on demand; the smaller extracted audio chunks are held in memory.
The CLI uses ffmpeg and ffprobe from PATH first, falling back to each
bundled tool when missing. Each tool is resolved independently, so a system copy
of one can be used alongside a bundled copy of the other. See
video tool setup for details.
Attachment failures produce warnings on stderr while the video still uploads.
Use videos repair --id <id> --file <original-file> to attach missing thumbnails
and audio without uploading the video again. Existing audio is preserved;
--thumbnail explicitly replaces a poster. Repair reports partial results and
exits nonzero if an attachment still fails.
Transcription runs asynchronously and requires server enablement and a running task worker. The web video page shows its status, text, and an SRT download. See video setup and recovery for local-server configuration and recovery limits.
Rawback can drive a Canon camera directly over CCAPI, where the camera itself is the HTTP server. Enable CCAPI in the camera's Wi-Fi menu first, note the address and port it shows, and set a user name and password there if you want one.
# Pair once; the camera becomes the default target
rawback camera connect 'http://user:password@192.168.0.1:8080'
rawback camera info
rawback camera status --json
rawback camera shoot --force
# Browse and pull files off the card
rawback camera contents storages
rawback camera contents list card1 100CANON --json
rawback camera contents get '<locator>' --output ./shot.jpgEvery endpoint the camera advertises is reachable, whether or not it has a dedicated command:
rawback camera api --list
rawback camera api shooting.getSetting --arg name=av --json
rawback camera interactive # full-screen explorerA camera serves one client at a time, so close the Canon app or Rawback
Desktop before connecting. Cameras also serve HTTPS with a self-signed
certificate; rawback verifies certificates by default and tells you to pass
--insecure when that is what you want.
# Describe what you want and let the server work out the filters
rawback photos search "from 2012, all images in NYC"
# Page through the same search without spending another AI credit
rawback photos search "from 2012, all images in NYC" --ai-search-id abc123 --page 2
# Search filenames and metadata literally
rawback photos list --search "Iceland"
# Combine filters; repeat or comma-separate multi-value filters
rawback photos list --camera-make Sony --rate 4,5 --has-gps
# Limit photos to a capture window
rawback photos list \
--captured-after 2026-01-01 \
--captured-before 2026-02-01
# Upload up to eight files in parallel
rawback photos upload --path ./photos --concurrency 8
# Inspect failed upload sessions
rawback uploads --status failed
# List and inspect daily dream recaps
rawback dream list
rawback dream get 42
# Retry a failed dream after an AI-credit warning
rawback dream retry 42
# Create and inspect an album
rawback album create --name "Iceland" --permission private
rawback album view 42
# Recollect the photos matching an album's smart filter
rawback album refresh 42
# Add photos and write the album's Markdown article
rawback album image add 42 108 109 110
rawback album article edit 42 --title "Iceland in winter" --content-file story.md
rawback album article publish 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
# List, create, and revoke SFTP credentials
rawback cred list
rawback cred add --name "Home workstation"
rawback cred del 7See the command reference for every command, option, default, and automation note. You can also ask the binary for context-specific help:
rawback --help
rawback photos search --help
rawback photos list --help
rawback photos upload --help
rawback dream --help
rawback config --help
rawback album --help
rawback album article --help
rawback shares list --helpRawback stores local state under ~/.rawback/:
| File | Purpose |
|---|---|
credentials.json |
Access and refresh tokens per environment, from rawback auth |
config.yml |
Environments, optional hosts, metadata workers, and SFTP |
upload-state.json |
Shared upload queue, history, and trusted host keys |
cameras.json |
Saved Canon cameras, shared with Rawback Desktop |
cameras.json is shared with the Rawback desktop app, so both can reach the same
camera without pairing twice. It holds a camera password only when you pass
rawback camera connect --save-password, and then in plain text at mode 0600 —
the same trade config.yml already makes for the SFTP password. Commands that
read it refuse a file that group or others can read.
The CLI creates credential, camera, upload-state, and config files with
restrictive permissions on Unix. config.yml is written on your first command
with the default hosts and a commented template for everything else, and upload
commands still require it to have mode 0600 on Unix — which matters if you
replace it by hand or copy it from another machine. Run rawback config init --force to put the annotated template back. Never commit files from
~/.rawback/ or paste their secrets
into issues and logs. rawback config view masks every sftp.password in both
terminal and JSON output, including the ones inside environments.
Install the pinned dependencies and run the CLI from source:
bun install --frozen-lockfile
bun run dev -- --helpRun the complete local validation suite and smoke-test the compiled binary:
bun run check
./dist/rawback --versionUseful focused checks are:
bun run typecheck
bun run test
bun run lint
bun run format:checkInstall the repository's pre-commit hooks with bun run hooks:install. More
architecture, SDK integration, testing, and release notes are in
the contributor guide. Coding agents should also read
AGENTS.md before making changes.
Release Please derives versions
and changelogs from Conventional Commits. Merging its release PR triggers
GoReleaser, which builds all six platform archives, signs and notarizes the
macOS binaries, publishes the Homebrew Cask, and includes a checksums.txt
file with each GitHub Release.
rawback album article versions 42 --json lists available languages and revisions.
Use view 42 --language fr or edit 42 --language fr --content-file story.md.
translate 42 --from en --to fr saves a translation for 10 credits, immediately
sharing the article's publication settings. Existing targets require --overwrite.
Use default 42 --language fr, label 42 --from und --to en, or
delete-version 42 --language fr under rawback album article to manage versions.
The default version cannot be deleted. All commands support --json.