Recording CLI Workflow

Use the Frametap CLI from an enrolled runner machine to create, list, and download recordings. This is the fastest workflow when you are already SSH'd into the VM, CI worker, container, or agent sandbox that produced the recording.

Agent/LLM summary

For local recording artifacts, use frametap recording list to discover document IDs, then frametap recording download <document-id> or frametap recording download --latest to retrieve the MP4. Listing and downloading use the stored runner token from frametap up; they do not require FRAMETAP_API_KEY, an org ID, or a running daemon.

Prerequisites

Install and enroll the runner:

bash

curl -fsSL https://cli.static.frametap.io/install | bash
frametap up --token ft_enrollment_xxxxxxxxxxxxxxxxx

Create at least one recording from this runner:

bash

frametap recording start --duration 30 --name "Checkout smoke test"

For manual recordings, omit --duration and stop when ready:

bash

frametap recording start --name "Manual repro"
frametap recording stop

List recordings

bash

frametap recording list

Default behavior:

Shows recordings created by this runner only.
Defaults to recordings created since the start of today in local time.
Uses stored runner credentials from enrollment.
Works even if frametapd is not currently running.

Example table output:

text

ID  NAME                  STATUS   SIZE      CREATED
42  Checkout smoke test   ready    8.4 MiB   2026-06-18 14:32:10
41  Manual repro          pending  -         2026-06-18 14:28:02

Time filtering with `--since`

Use relative durations:

bash

frametap recording list --since 30m
frametap recording list --since 12h
frametap recording list --since 3d
frametap recording list --since 1w

Use absolute dates:

bash

frametap recording list --since 2026-06-01

Invalid values fail with a clear non-zero error:

bash

frametap recording list --since yesterday
# Error: invalid --since value "yesterday"; use 30m, 12h, 1d, 1w, or YYYY-MM-DD

Limit results

bash

frametap recording list --limit 20

JSON output for scripts and agents

bash

frametap recording list --since 1d --limit 20 --json

Example JSON:

json

[
  {
    "id": 42,
    "title": "Checkout smoke test",
    "type": "video",
    "status": "ready",
    "size": 8808038,
    "createdAt": "2026-06-18T14:32:10Z"
  }
]

Stable fields:

Field	Meaning
`id`	Recording document ID. Pass this to `frametap recording download <id>`.
`title`	Recording/job name. May be empty.
`type`	Document type; recordings are `video`.
`status`	`pending`, `ready`, `failed`, or `deleted`. Only `ready` recordings can be downloaded.
`size`	Primary MP4 size in bytes, or `null` while not ready.
`createdAt`	ISO timestamp.

Download a recording

Download by document ID from recording list:

bash

frametap recording download 42

By default, the file is written to the current directory. The filename comes from the server-provided recording filename, with a fallback like 42.mp4.

Example output:

text

/home/me/project/Checkout smoke test.mp4

Choose a destination directory

bash

frametap recording download 42 --path /tmp/artifacts

--path must already exist and must be writable. If the directory is missing or not writable, the command exits non-zero with a clear error.

Download the latest ready recording

bash

frametap recording download --latest
frametap recording download --latest --path /tmp/artifacts

--latest is convenient in CI or agent workflows when the runner just created one recording and you want the newest ready artifact.

End-to-end CLI example

bash

# Create a 15 second recording.
frametap recording start --duration 15 --name "Login smoke test"

# Find recent recordings from this runner.
frametap recording list --since 1h

# Download the newest ready recording into an artifacts directory.
mkdir -p /tmp/frametap-artifacts
frametap recording download --latest --path /tmp/frametap-artifacts

# Confirm the MP4 exists.
ls -lh /tmp/frametap-artifacts

Authentication and security model

Recording list/download commands use the runner token stored during frametap up. They do not need a user API key or organization ID.

Security properties:

A runner can only list recordings created by that runner.
A runner can only download recordings created by that runner.
Document IDs from another runner return recording not found rather than revealing whether the document exists.
Signed download URLs are short-lived and generated by the Frametap API.

Daemon behavior

recording start, recording stop, recording status, recording abort, and screenshot need the daemon because they capture from the local display (or manage local capture state).

recording list and recording download are direct HTTPS API calls with stored runner credentials, so they work after:

bash

frametap down

They stop working after:

bash

frametap logout

because logout clears the stored runner credentials.

Troubleshooting

`runner is not enrolled. Run 'frametap up --token ...' first`

The CLI cannot find stored runner credentials. Enroll the runner again:

bash

frametap up --token ft_enrollment_xxxxxxxxxxxxxxxxx

`recording not found`

Common causes:

The document ID is wrong.
The recording belongs to a different runner.
The recording was deleted.
The ID is not a recording document.

Run:

bash

frametap recording list --since 1w

to find IDs available to this runner.

`recording is not ready yet`

The recording exists, but the MP4 has not finished uploading/processing. Wait and retry:

bash

frametap recording list --since 1h
frametap recording download <document-id>

`runner busy` / `no active recording exists` (wedged state)

The daemon can enter a wedged state where frametap recording start returns runner busy, but frametap recording stop returns no active recording exists. This happens when a recording process died without signaling completion, leaving stale local recording state.

Inspect both the local and backend views:

bash

frametap recording status

If the local and backend views disagree (for example, the backend holds a stale running job but the local daemon is idle), recover without restarting or re-enrolling the daemon:

bash

frametap recording abort

abort clears the local capture slot, terminates any lingering capture process, and cancels the active recording job on the backend. After abort, you can start a new recording immediately.

`download path does not exist` or `download path is not writable`

Create the directory and ensure the current user can write to it:

bash

mkdir -p /tmp/frametap-artifacts
frametap recording download <document-id> --path /tmp/frametap-artifacts

Recording CLI Workflow ​

Prerequisites ​

List recordings ​

Time filtering with --since ​

Limit results ​

JSON output for scripts and agents ​

Download a recording ​

Choose a destination directory ​

Download the latest ready recording ​

End-to-end CLI example ​

Authentication and security model ​

Daemon behavior ​

Troubleshooting ​

runner is not enrolled. Run 'frametap up --token ...' first ​

recording not found ​

recording is not ready yet ​

runner busy / no active recording exists (wedged state) ​

download path does not exist or download path is not writable ​

Related pages ​

Recording CLI Workflow

Prerequisites

List recordings

Time filtering with `--since`

Limit results

JSON output for scripts and agents

Download a recording

Choose a destination directory

Download the latest ready recording

End-to-end CLI example

Authentication and security model

Daemon behavior

Troubleshooting

`runner is not enrolled. Run 'frametap up --token ...' first`

`recording not found`

`recording is not ready yet`

`runner busy` / `no active recording exists` (wedged state)

`download path does not exist` or `download path is not writable`

Related pages