CLI Commands Reference

The Frametap CLI is how you install, enroll, inspect, and manage a Frametap runner locally.

Using an LLM or coding agent?

Load the Frametap Agent Skill or the raw skill/SKILL.md file for a compact agent-ready reference to Frametap CLI, API, runner, and capture workflows.

Overview

frametap [command] [flags]

Global Commands

`frametap status`

Show daemon status, version, runner info, and platform details.

bash

frametap status

Output:

Version:     1.0.0
Uptime:      2h 15m
Runner:      runner-abc123 (online)
Platform:    linux/amd64
Hostname:    my-server
Watch Dir:   /app/output

`frametap up`

Enroll a runner and start the daemon.

bash

frametap up --token <token> [flags]

Flags:

--token <token> - Enrollment token (or use FRAMETAP_TOKEN)
--hostname <name> - Custom runner name (default: OS hostname)
--watch <path> - Absolute path to watch folder
--yes - Only used with --watch; accepts watch-folder warnings, such as prompts about uploading many existing files

Examples:

bash

# Basic enrollment
frametap up --token ft_enrollment_xxxxxxxx

# With custom name and watch folder
frametap up --token ft_enrollment_xxxxxxxx \
  --hostname "ci-runner-1" \
  --watch /app/screenshots \
  --yes

Behavior:

Validates the token immediately
Exits with error if token is invalid or expired
Starts frametapd in the background if not already running
Idempotent: safe to run multiple times with same token

`frametap down`

Stop the daemon while preserving runner credentials.

bash

frametap down

Behavior:

Stops daemon process
Keeps the stored runner so frametap up can reconnect later

`frametap logout`

Stop the daemon and clear stored runner credentials.

bash

frametap logout

Display Commands

`frametap displays`

List available displays.

bash

frametap displays

Output:

Display ID    Resolution    Primary
:0            1920x1080     *
:1            1280x720

Use the Display ID when creating jobs from the CLI, in Jobs, or through the API.

Job Commands

`frametap recording start`

Start a recording from the current runner.

bash

frametap recording start [flags]

Flags:

--display <id> - Display ID from frametap displays
--duration <seconds> - Recording duration in seconds; automatically stops when the duration is reached
--name <name> - Optional job name
--wait - Wait until the daemon confirms recording start or returns an error (default)
--no-wait - Return after the recording start request is accepted, without waiting for confirmation

--wait and --no-wait cannot be used together.

Examples:

bash

# Start an interrupt recording on the default display
frametap recording start --name "Manual repro"

# Record display :0 for 30 seconds
frametap recording start \
  --display :0 \
  --duration 30 \
  --name "Checkout smoke test"

If you omit --duration, the recording runs as an interrupt recording until you stop it.

`frametap recording stop`

Stop the active interrupt recording on the current runner.

bash

frametap recording stop

Use this for recordings started with frametap recording start without --duration.

`frametap recording status`

Show local and backend recording state for the current runner.

bash

frametap recording status

Output is JSON with two sections:

local - daemon recording state: active, jobId, displayId, processState, staleLock, and related metadata.
backend - the API's view of the runner's active recording, fetched via GET /v1/runners/me/recordings/current.

Use this to diagnose a wedged state where recording start reports runner busy but recording stop reports no active recording exists. If the local and backend views disagree, run frametap recording abort to recover.

`frametap recording abort`

Force-clean local recording state and cancel any active recording on the current runner.

bash

frametap recording abort

This clears the local capture slot (terminating any lingering capture process) and cancels the active recording job on the backend. Use it to recover from a wedged runner busy / no active recording exists state without restarting or re-enrolling the daemon (frametap down + frametap up).

The daemon must be running (verify with frametap status). After abort, you can start a new recording immediately.

`frametap recording list`

List recordings created by the currently enrolled runner.

bash

frametap recording list [flags]

Flags:

--since <value> - Show recordings created since a relative duration (30m, 12h, 1d, 1w) or absolute date (YYYY-MM-DD). Default: start of today in local time.
--limit <n> - Maximum number of recordings to return.
--json - Print stable JSON output for scripts and agents.

Examples:

bash

# Today's recordings from this runner
frametap recording list

# Last 3 days
frametap recording list --since 3d

# Script-friendly output
frametap recording list --since 1d --limit 20 --json

Table output includes ID, NAME, STATUS, SIZE, and CREATED. Use the ID with frametap recording download <document-id>.

No API key needed

recording list uses the stored runner token from frametap up. It does not require FRAMETAP_API_KEY or an organization ID, and it works even when the daemon is stopped with frametap down.

`frametap recording download`

Download a recording created by the currently enrolled runner.

bash

frametap recording download <document-id> [flags]
frametap recording download --latest [flags]

Flags:

--path <dir> - Existing writable directory to write the MP4. Default: current directory.
--latest - Download the most recent ready recording visible to this runner.

Examples:

bash

# Download by document ID from `recording list`
frametap recording download 42

# Download to an artifacts directory
mkdir -p /tmp/artifacts
frametap recording download 42 --path /tmp/artifacts

# Convenience: download the newest ready recording
frametap recording download --latest --path /tmp/artifacts

The command prints the final file path on success. If the recording belongs to another runner, the CLI exits non-zero with recording not found. If the recording still has status pending, it exits with recording is not ready yet.

See the Recording CLI Workflow for an end-to-end guide, JSON schema, daemon behavior, and troubleshooting.

`frametap screenshot`

Capture a screenshot from the current runner.

bash

frametap screenshot [flags]

Flags:

--display <id> - Display ID from frametap displays
--name <name> - Optional job name

Examples:

bash

# Capture the default display
frametap screenshot --name "Before checkout"

# Capture a specific display
frametap screenshot --display :0 --name "Dashboard state"

Recording capture and screenshot commands require the runner daemon to be enrolled and running. Use frametap status to confirm the runner is online before starting a job. recording status and recording abort also require the daemon. frametap recording list and frametap recording download only need stored runner credentials and continue to work after frametap down.

Watch Folder Commands

`frametap watch start`

Start monitoring a directory for file uploads.

bash

frametap watch start --dir <path> [flags]

Flags:

--dir <path> - Absolute path to watch (required)
--exclude <glob> - Exclude pattern (repeatable)
--yes - Accept watch-folder warnings, such as prompts about uploading many existing files

Example:

bash

frametap watch start \
  --dir /app/output \
  --exclude "*.log" \
  --exclude "*.tmp"

Requirements:

Path must be absolute (e.g., /home/user/files)
No symlinks in path
User must have read permissions

`frametap watch stop`

Stop watching directory.

bash

frametap watch stop

`frametap watch status`

Show watch configuration.

bash

frametap watch status

Output:

Watching:    true
Directory:   /app/output
Exclusions:  *.log, *.tmp

Daemon Commands

`frametap daemon start`

Start daemon in foreground (for debugging).

bash

frametap daemon start

`frametap daemon socket`

Print daemon socket path.

bash

frametap daemon socket

Output:

~/.config/frametap/daemon.sock

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	Daemon not running
4	Invalid/expired token
5	Permission denied
6	File not found
7	Network error

Tips

Shell Completion

bash

# Bash
source <(frametap completion bash)

# Zsh
source <(frametap completion zsh)

# Fish
frametap completion fish | source

Alias for Common Commands

bash

# Add to .bashrc or .zshrc
alias ft='frametap'
alias ft-up='frametap up --token $FRAMETAP_TOKEN'
alias ft-status='frametap status'

Watch Multiple Directories

While you can only watch one directory per runner, you can run multiple runners:

bash

# Runner 1 - screenshots
FRAMETAP_HOSTNAME=runner-1 frametap up --watch /app/screenshots

# Runner 2 - logs
FRAMETAP_HOSTNAME=runner-2 frametap up --watch /app/logs

CLI Commands Reference ​

Overview ​

Global Commands ​

frametap status ​

frametap up ​

frametap down ​

frametap logout ​

Display Commands ​

frametap displays ​

Job Commands ​

frametap recording start ​

frametap recording stop ​

frametap recording status ​

frametap recording abort ​

frametap recording list ​

frametap recording download ​

frametap screenshot ​

Watch Folder Commands ​

frametap watch start ​

frametap watch stop ​

frametap watch status ​

Daemon Commands ​

frametap daemon start ​

frametap daemon socket ​

Exit Codes ​

Related Pages ​

Tips ​

Shell Completion ​

Alias for Common Commands ​

Watch Multiple Directories ​

CLI Commands Reference

Overview

Global Commands

`frametap status`

`frametap up`

`frametap down`

`frametap logout`

Display Commands

`frametap displays`

Job Commands

`frametap recording start`

`frametap recording stop`

`frametap recording status`

`frametap recording abort`

`frametap recording list`

`frametap recording download`

`frametap screenshot`

Watch Folder Commands

`frametap watch start`

`frametap watch stop`

`frametap watch status`

Daemon Commands

`frametap daemon start`

`frametap daemon socket`

Exit Codes

Related Pages

Tips

Shell Completion

Alias for Common Commands

Watch Multiple Directories