5AM CLI Reference

Install

macOS & Linux (One-liner script)

The easiest way to install or upgrade the 5am CLI on macOS (Apple Silicon & Intel) and Linux (x86_64 & ARM64) is using our installation script:

curl -fsSL https://cli.5am.app/cli/latest/install.sh | sh

Windows (PowerShell)

Invoke-WebRequest https://cli.5am.app/cli/latest/5am-windows-amd64.exe -OutFile 5am.exe
./5am.exe --version

Verify integrity against the published .sha256:

curl -L https://cli.5am.app/cli/latest/5am-darwin-arm64.sha256
shasum -a 256 5am

Self-update

Once installed, the CLI keeps itself current:

5am update           # download + install the latest release in place
5am update --check   # just print whether a newer version is available

5am update automatically handles fetching the latest binary, verifying integrity, and atomically replacing the executable.

Getting Started

Authentication

Mint a personal access token in the web UI at Settings → CLI Access Tokens by clicking Generate token. Pick scopes (read, write, admin) and copy the token.

5am login                  # paste token at the prompt
5am login --token <TOKEN>  # or pass directly
5am whoami                 # verify

Alternatively, pass it via environment variable: 5AM_TOKEN=<TOKEN> 5am whoami.

Tab Completion

The CLI ships completion scripts for bash, zsh, fish, and PowerShell. Once installed, <tab> expands commands, flags, and options.

# zsh
mkdir -p ~/.zsh/completions
5am completion zsh > ~/.zsh/completions/_5am

# Add to ~/.zshrc (before `compinit` runs):
#   fpath=(~/.zsh/completions $fpath)
exec zsh

Commands

Account

5am account                                # storage usage, plan, subscription
5am account --pretty                       # human-readable summary

Albums

You can obtain an <albumId> by running the 5am albums list command.

5am albums list                            # albums YOU own
5am albums list-shared                     # albums others have shared with you
5am albums shares <albumId>                # view all people who have access to this album
5am albums get <albumId>                   # fetch metadata for a single album
5am albums create --name "Trip 2026"
5am albums update <albumId> --name "Trip 2027" --description "Best trip ever"
5am albums delete <albumId> --yes

# Download all media from an album to a local directory
5am albums download <albumId> --output ./trip_photos --type image

# Generate an AI-powered natural language summary of the album's contents
5am albums generate-summary <albumId>

Sharing an Album

# Share with an email (read-only)
5am albums share <albumId> --share [email protected]

# Revoke a share
5am albums unshare <albumId> --user [email protected]

# Enable/Disable a public link (usable as ?shareToken=...)
5am albums public-link enable <albumId>
5am albums public-link disable <albumId>

Command Arguments:

• <albumId>: The ID of the album.
• --name: The name of the album (used for creation or updating).
• --description: A description of the album.
• --location: The location associated with the album.
• --share: Accepts a single email, or a list of emails separated by a comma (e.g., [email protected],[email protected]).
• --user: The email address of the person whose access you want to revoke.

Media Management

Upload files, globs, or whole directories. HEIC/HEIF files are automatically converted to JPEG locally on macOS and Linux.

The CLI is the only client that can upload videos up to 10 GB (the web and mobile apps cap at 2 GB; requires a Premium or Ultra plan). Videos over 2 GB are processed locally before upload — the CLI extracts the poster and, when needed, encodes a web-playable 1080p proxy — so they need a local FFmpeg. Large files upload several parts in parallel per file, and interrupted uploads resume: if the connection dies partway, just run the same command again within a few days — already-uploaded parts (and the transcoded proxy) are reused, so only the missing pieces move.

5am media list                             # list all media
5am media list --album <albumId>           # list media in a specific album
5am media upload ./photos/*.jpg --album "Trip 2026"
5am media upload ./photos -r --new-album "Imports 2026"
5am media upload ./footage/interview-4k.mov --album "Shoots"   # videos up to 10 GB (Premium/Ultra; ffmpeg needed over 2 GB)
5am media download <mediaId> --output ./photo.jpg
5am media delete <mediaId> --yes

# Vector search by meaning (vs lexical --search)
5am media semantic-search "sunsets at the beach"

# Local File Operations
5am media convert photo.heic --output photo.jpg
5am media resize cover.png --width 1920 --output cover_resized.png
5am media smartcrop photo.jpg --size 1080x1350 --output crop.jpg   # AI subject-aware crop — see "AI Smart Crop" below
5am media concat clip1.mp4 clip2.mp4 clip3.mp4 --output merged.mp4
5am media mix --voice episode.wav --music bed.mp3 --output mix.wav

# Timestamped, speaker-labeled AI transcript of a local video/audio file
# (json, srt, or vtt — feeds the AI video tools at /cli/docs/ai-video-clip)
5am media transcribe talk.mp4
5am media transcribe episode.wav --format srt -o episode.srt

# Generate an AI description at upload time, computed locally with your
# Gemini key: images get classifier tags + a search description; video/audio
# a summary of the audio track — works even for 10 GB files
5am media upload ./footage -r --album "Shoots" --describe

# Generate an AI-powered natural language summary of a media file
5am media generate-summary <mediaId>

Command Arguments:

• --album: Adds the uploaded media to an existing album by name or ID.
• --new-album: Creates a new album with the specified name and adds the media to it.
• -r: Recursively scans directories for media files.
• --part-concurrency: Parallel multipart parts per file for large uploads (default 4).
• --ffmpeg: Path to the ffmpeg binary (default: $FFMPEG, then PATH); required for videos over 2 GB.
• --describe: Generate an AI description for each upload with your Gemini key — images get classifier tags + a search description, video/audio a summary of the audio track (ffmpeg required for video/audio).
• <mediaId>: The ID of the specific media file (obtainable by running 5am media list).

AI Smart Crop

Crop photos to a target size or aspect ratio with AI subject detection: Gemini Vision locates the main subject (faces first) and the crop keeps it fully in frame, instead of blindly cutting the center. Perfect for turning a landscape shot into an Instagram portrait or a square thumbnail without decapitating anyone. Image processing runs locally in the CLI — only the small detection call uses your Gemini key.

# Exact output size: crop to the 4:5 region around the subject, then scale to 1080x1350
5am media smartcrop photo.jpg --clue "make sure faces are in the frame" \
  --size 1080x1350 --output crop.jpg

# Aspect-ratio mode: the largest 4:5 region at native resolution, never resampled
5am media smartcrop photo.jpg --aspect 4:5 --output crop.jpg

# Literal pixel window: cut exactly 1080x1080 from the source, no scaling
5am media smartcrop photo.jpg --size 1080x1080 --no-scale --output crop.jpg

# Batch a local folder — or an entire album straight from your account.
# Files land in --output-dir as <name>-smartcrop.<ext>
5am media smartcrop --folder ./photos --aspect 1:1 --output-dir ./cropped
5am media smartcrop --album "Trip 2026" --size 1080x1350 --output-dir ./cropped

Command Arguments:

• --clue: Optional plain-language guidance for the detector (e.g., "keep both people", "focus on the red car"). Overrides the default face-first preference when they conflict.
• --size: Exact output size in pixels as WxH (e.g., 1080x1350) — crops to that aspect around the subject, then scales to exactly that size.
• --aspect: Target aspect ratio as W:H (any integer ratio: 4:5, 3:2, 16:9, ...) — crops the largest matching region at native resolution, never resampled.
• --no-scale: With --size, cut a literal WxH pixel window instead of crop-and-scale (errors if the source is smaller).
• --output / --output-dir: Output file for single-photo mode, or the output directory for batch mode (multiple paths, --folder, or --album).
• --quality: JPEG output quality 1–100 (default 90; PNG and WebP are unaffected).
• --cache: Path of the local subject-box cache (default ~/.5am/collage-subjects.json, shared with 5am media collage --smart-crop — a photo detected by one is a free cache hit for the other).

Local Slideshow

Launch a local web server to view a beautiful, full-screen slideshow of media. Navigate with the Left/Right arrows, Space to pause/play, and f for fullscreen.

5am media slideshow --folder ./photos --delay 5s
5am media slideshow --album "Trip 2026" --delay 10s --metadata
5am media slideshow --album all --delay 8s --metadata          # every album, in one continuous slideshow

Smooth playback. The next few slides are prefetched while the current one plays, so videos start without a stall instead of buffering cold on first play. For album sources, the slideshow streams the lighter, faster version of each item when your library has one — a video's converted (+faststart) MP4 rather than the raw .mov, and a large image variant rather than the full-resolution original — falling back to the original when no variant exists.

On-disk cache (albums). Each album item is downloaded from your account once and cached on disk (default ~/.5am/slideshow-cache, capped at 2 GB), then served locally on every subsequent loop. This survives browser cache eviction and persists across runs, so looping a large album doesn't re-download it every pass. The cache serves HTTP Range requests, so video seeking and replay keep working.

5am media slideshow --album "Trip 2026" --cache-size 8192              # bump the cap to 8 GB
5am media slideshow --album "Trip 2026" --cache-dir /mnt/ssd/5am-cache # custom location
5am media slideshow --album "Trip 2026" --no-cache                     # always fetch from the backend
5am media slideshow --album "Trip 2026" --cache-size 0                 # unbounded (no eviction)

Command Arguments:

• --folder: Path to a local directory containing images.
• --album: An album name or ID to stream directly from your 5AM account, or all to play every album in one continuous slideshow.
• --delay: Duration to show each image before transitioning (e.g., 5s, 10s).
• --metadata: Overlays EXIF metadata and AI-generated descriptions on the slideshow.
• --host: IP to bind the local server to (default 127.0.0.1; use 0.0.0.0 for LAN access).
• --no-cache: Disable the on-disk media cache (albums only); always fetch from your account.
• --cache-dir: Directory for the on-disk media cache (default ~/.5am/slideshow-cache).
• --cache-size: Max cache size in MB (default 2048; 0 = unbounded).

Search

# Lexical search (filenames, EXIF, etc.)
5am media list --album <albumId> --search "sunset"

# Semantic AI search (finds photos that "look like" the query)
5am media semantic-search "sunsets at the beach"

AI Media Generation

Generate images, video, audio, and text using local CLI commands.

# Image Generation (gemini-2.5-flash-image, gemini-3.1-flash-image, gemini-3-pro-image)
5am media generate image --prompt "a cybernetic owl" --provider gemini --output owl.png

# Image editing / composition: mix the prompt with input images (repeat --image, up to 14)
5am media generate image --prompt "put this logo on a coffee mug, photorealistic" \
  --image logo.png --image mug.jpg --model gemini-3-pro-image --output mockup.png

# Aspect ratio + resolution (resolution is Gemini 3.x-only: 512 | 1K | 2K | 4K)
5am media generate image --prompt "a desert highway at golden hour" \
  --model gemini-3.1-flash-image --aspect-ratio 16:9 --resolution 2K --output road.png

# Google Search grounding: base the image on real-time facts (weather, events, data)
5am media generate image --prompt "a chart of today's weather in San Francisco" \
  --model gemini-3.1-flash-image --grounding --aspect-ratio 16:9 --output weather.png

# Video Generation (Veo)
5am media generate video --prompt "a flowing river in autumn" --output river.mp4

# Image-to-video: animate from an initial frame — or interpolate to a last frame
5am media generate video --prompt "slow zoom out" --image start.png --output clip.mp4
5am media generate video --prompt "she fades away" --image first.png --last-frame last.png --output interp.mp4

# Asset reference images: keep a person, product, or garment consistent
# (repeatable; cannot combine with --image/--last-frame)
5am media generate video --prompt "office group photo, funny faces" \
  --reference-image person1.png --reference-image person2.png --output group.mp4

# Video extension: continue a previously generated Veo clip from where it ended (720p only)
5am media generate video --prompt "track the butterfly into the garden" \
  --extend butterfly.mp4 --output butterfly-extended.mp4

# Get a native desktop notification when a slow generation finishes (see "Desktop Notifications" below)
5am media generate video --prompt "a flowing river in autumn" --output river.mp4 --notify

# Audio & Music
5am media generate music --prompt "lo-fi hip hop for studying" --output chill.mp3
5am media generate audio --text "Hello, I am your AI assistant" --voice Puck --output hello.wav

# Text Generation
5am media generate text --prompt "Write a short poem about an AI learning to code" --output poem.txt

# Multimodal text: ask about local images (repeatable --image)
5am media generate text --prompt "Tell me about this instrument" --image organ.jpg

# Audio, video, or PDF input (repeatable --file)
5am media generate text --prompt "Summarize this lecture in five bullets" --file lecture.mp3

Command Arguments:

• --prompt: The textual description of what the AI should generate.
• --provider: Which AI model provider to use (e.g., gemini, openai).
• --model: Specific AI model to use (see Supported Models below).
• --output: The local file path where the generated media will be saved.
• --text: The text script for text-to-speech generation.
• --voice: The named voice profile to use for speech generation.
• --image / --last-frame (video): First frame for image-to-video; add --last-frame to interpolate between two frames (--last-frame requires --image).
• --reference-image (video, repeatable): Asset reference images (.png/.jpg/.webp) so a person, product, or garment stays consistent in the generated clip. Cannot be combined with --image/--last-frame.
• --extend (video): Continue a previously generated Veo clip (.mp4/.mov/.webm) from where it ended. Limited to 720p by the Veo API; cannot be combined with --image/--last-frame/--reference-image.
• --image (image, repeatable): Input/reference images for editing or composition — edit a photo, combine subjects, apply a style. Up to 14 per request on the Gemini 3.x models.
• --aspect-ratio, --resolution (image): Any supported ratio (1:1, 16:9, 4:5, 21:9, ...); size 512/1K/2K/4K on Gemini 3.x models (gemini-2.5-flash-image is 1024px only).
• --grounding, --grounding-images (image): Ground the image in real-time Google Search results (weather, events, live data); --grounding-images additionally uses image-search results as visual context (gemini-3.1-flash-image only).
• --image (text, repeatable): Include local images alongside a text prompt — describe a photo, write alt text, extract or compare visual details.
• --file (text, repeatable): Include audio (.mp3/.wav/.m4a/.aac/.flac/.ogg), video (.mp4/.mov/.webm), or .pdf files with the prompt — summarize a recording, answer questions about a document. Uploaded via the Gemini Files API and deleted after.
• --aspect-ratio, --resolution, --duration, --negative-prompt (video): 16:9/9:16; 720p/1080p/4k (4k not available on the Lite model; higher resolutions render slower and cost more); clip length in seconds; what to avoid.

Supported Models (Gemini):

• Image: gemini-3.1-flash-image, gemini-3-pro-image, gemini-2.5-flash-image
• Video (Veo): veo-3.1-generate-preview, veo-3.1-fast-generate-preview, veo-3.1-lite-generate-preview
• Text: gemini-3-flash-preview, gemini-3.7-flash, gemini-3.5-flash-lite, gemini-2.5-flash, gemini-2.5-pro

Desktop Notifications (--notify)

The long-running, "go make coffee" commands can ping you with a native OS notification the moment they finish — useful when you kick off a minutes-long generation, switch to another window, and don't want to babysit the terminal.

# Notify when this command completes
5am media generate video --prompt "a flowing river in autumn" --output river.mp4 --notify

# Or turn it on for the whole session via an environment variable
5AM_NOTIFY=1 5am media collage --folder ./photos --music "warm piano" --output memory.mp4

--notify is a global flag (off by default) and is honored by the commands that actually take a while: media generate image|video|music|audio, media collage, media concat, media visualize, media mix, and albums download. Fast commands ignore it.

AI Video Editing — Highlights & Clips

The audio/video production tools moved to their own page: podcast & video tools (media visualize, the podcast-to-video helper, and the media mix auto-ducking), AI highlight reels (5am media highlight and the edit subcommands), AI short clips & Clip Maker (5am media clips and 5am studio), memory collage videos (5am media collage), and the full VEDL language reference.

AI Video Editing reference →

AI Characters & Agents

Everything character-related moved to its own page: creating and chatting with AI Characters, webhooks, server skills, API keys, custom local skills, Server Agents & datasets, and the multi-character AI Playground.

AI Characters & Agents reference →

Examples

Batch Resize, Convert, and Upload Images Recursively (macOS and Linux)

Since 5am media resize operates on a single file at a time and preserves the input format, you can combine it with 5am media convert and 5am media upload in a simple shell loop to batch process, resize, convert, and upload a directory of images (e.g., converting all .png files to .jpg resized to 1920px width, and uploading them to a target 5AM album):

# Find all PNGs recursively, resize them to 1920px width,
# convert them to JPG, and upload them to a 5AM album
find ./photos -type f -name "*.png" | while read -r img; do
  # Determine temp and target paths
  temp_resized="${img%.*}_resized.png"
  target_jpg="${img%.*}_resized.jpg"
  
  # 1. Resize the image (PNG -> PNG)
  5am media resize "$img" --width 1920 --output "$temp_resized"
  
  # 2. Convert to JPEG (PNG -> JPEG)
  5am media convert "$temp_resized" --output "$target_jpg" --quality 90
  
  # 3. Upload to 5AM album
  5am media upload "$target_jpg" --album <albumId-or-name>
  
  # Clean up temporary files
  rm "$temp_resized"
  rm "$target_jpg"
done

FAQ

What exactly is considered a "media file"?
A media file in 5AM encompasses all common image, video, and audio formats. This includes standard images (.jpg, .png, .webp, .gif), Apple's high-efficiency image formats (.heic, .heif), all standard video formats (.mp4, .mov, etc.), and audio formats (.mp3, .wav, etc.).

Where are my API keys stored?
The CLI securely stores your API keys in your system's native keychain (Keychain Access on macOS, Secret Service on Linux, Credential Manager on Windows) if available. If a native keychain is not available, it falls back to storing configuration locally in ~/.config/5am/ (or your OS equivalent).

Why do some media commands fail saying ffmpeg is missing?
Advanced media commands, such as 5am media visualize, 5am media concat, 5am media collage, 5am media mix, 5am media transcribe, and uploading videos larger than 2 GB, require the powerful FFmpeg library to process media. You can install it via your system's package manager (e.g., brew install ffmpeg on macOS, apt install ffmpeg on Linux, or winget install ffmpeg on Windows).

Does it work offline?
Commands that interact with the 5AM platform or AI providers require an internet connection. Local conversion and visualization commands (media convert, media visualize) run entirely offline.