The faylee CLI

The faylee command reads recordings from a terminal, a script or an agent’s shell. It lists recent recordings and prints a recording’s console, network, steps, transcript and more, one event per line. It also saves frames as image files and makes recording links. faylee mcp relays Faylee’s MCP server over stdio, for agents that can only start a local command.

Installing

The CLI is not published to npm. It comes as a single JavaScript file, faylee.js, that runs on Node.js 20 or later. Ask your Faylee contact for the current build, then put it on your PATH as faylee:

chmod +x faylee.js
mv faylee.js ~/.local/bin/faylee
faylee

Run with no command, faylee prints its usage.

Signing in

The CLI reads two environment variables:

Variable	Value
`FAYLEE_URL`	`https://app.faylee.app`
`FAYLEE_TOKEN`	A personal token

To create a token, open Settings, Browsers and tokens in Faylee. Under Tokens for the CLI and agents, name the token after what it’s for, such as “Claude Code on my laptop”, and click Create token. The token is shown once, so copy it then.

export FAYLEE_URL=https://app.faylee.app
export FAYLEE_TOKEN=<token>
faylee list --problems

The token reads what you can read in the workspace. To stop it working, revoke it in Browsers and tokens.

Naming a recording

Wherever a command takes <link>, you can pass anything a person pastes: a share link, an embed or dashboard URL, a share id or a recording id. A ?t= in the link is ignored.

faylee show https://app.faylee.app/s/AbC123xYz0
faylee show AbC123xYz0

Commands

Command	Prints
`list`	Recent recordings in the workspace, one per line
`show <link>`	Title, page, counts, what the reporter wrote, and the assistant’s analysis
`evidence <link>`	Every event, one per line, as the assistant reads it
`console <link>`	Console output and uncaught errors, with stacks
`network <link>`	Requests with an id, status and timing, and why failed ones failed
`request <link> <id>`	One request in full, with a cURL command
`steps <link>`	Numbered reproduction steps
`chapters <link>`	The recording split into chapters, as a map of it
`sockets <link>`	WebSocket and EventSource connections and their messages
`transcript <link>`	What the reporter said while recording
`frames <link>`	Saves frames as JPEG files and prints their paths
`link <title>`	Makes a recording link and prints it
`mcp`	Relays a local MCP client to Faylee’s MCP server

Every event line starts with the time into the recording, such as [0:12.4]. Lines from different commands, and the frames, line up on the same clock.

list

faylee list [--problems] [--since <ISO time>] [--query <text>]

Each line has the share id, when the recording was made, its kind, the number of problems when there are any, and its title.

Flag	Effect
`--problems`	Only recordings with errors or failed requests
`--since <ISO time>`	Only recordings made since this time, such as `2026-09-01T00:00:00Z`
`--query <text>`	Only recordings that match this text

show

faylee show <link>

The title and link, the kind, length, date and who reported it, the page, the number of errors and failed requests, and the tags. Then what the reporter wrote, the assistant’s summary, actual and expected behaviour, likely cause and where to look, and recordings that failed in some of the same ways.

evidence

faylee evidence <link>

The whole capture as the assistant reads it: steps, console, network, sockets, environment, app metadata and backend errors, one event per line. Stack traces are resolved to the original source when the page’s source maps are public. Use it to hand a recording to a model in one go.

console

faylee console <link> [--errors] [--search <text>]

Flag	Effect
`--errors`	Only errors and uncaught exceptions
`--search <text>`	Only lines containing this text, ignoring case

network

faylee network <link> [--failed] [--search <text>]

Each line has the time, the request’s id after #, the method, status, duration and URL, and the GraphQL operation when there is one. A failed request has a second line with the reason, such as a CORS block or GraphQL errors.

Flag	Effect
`--failed`	Only failed requests
`--search <text>`	Only requests whose URL or GraphQL operation contains this text

request

faylee request <link> <id>

One request in full, with its headers, bodies and a cURL command. Pass the id from faylee network without the #:

faylee request AbC123xYz0 42

steps

faylee steps <link>

The steps to reproduce, numbered, each with its time.

chapters

faylee chapters <link>

The recording split into chapters, each with its start and end time, kind, title and number of problems. A new chapter starts at a page change, at the first failure after a quiet stretch, and where the person acted or spoke again after a pause. It is a quick way to see the shape of a long recording.

sockets

faylee sockets <link> [--search <text>]

WebSocket and EventSource connections with their messages. --search keeps only messages containing the text.

transcript

faylee transcript <link>

What the reporter said while recording, with times.

frames

faylee frames <link> [--at <ms,ms>] [--from <ms> --to <ms> --count <n>] [--size small|medium|large] [--out <dir>]

Downloads frames as JPEG files and prints the path of each, so a script or agent can open them. With no times, it saves one labelled overview image, overview.jpg. Other frames are named by their time in milliseconds, such as 82000.jpg.

Flag	Effect
`--at <ms,ms>`	Frames at these times, in milliseconds, separated by commas
`--from <ms> --to <ms> --count <n>`	Frames spread across a stretch of the recording
`--size`	`small`, `medium` or `large`
`--out <dir>`	Where to save them. By default, `faylee-frames/<id>` in the current directory.

link

faylee link <title> [--message <text>] [--ref <url>] [--days <n>]

Makes a recording link and prints it. Anyone with the link can record their screen and send it to your workspace, with no account or extension. See Recording links.

Flag	Effect
`--message <text>`	Instructions shown to the person
`--ref <url>`	The ticket or conversation it is for. Zendesk and Intercom tickets get a note when the recording arrives. See Zendesk and Intercom.
`--days <n>`	How many days the link works

mcp

faylee mcp

Relays MCP over stdio to Faylee’s MCP server, with your personal token. Most agents connect to https://app.faylee.app/mcp directly and sign in through the browser. Use faylee mcp for a client that can only start a local command:

claude mcp add faylee --env FAYLEE_URL=https://app.faylee.app --env FAYLEE_TOKEN=<token> -- faylee mcp

The tools, the guide and the prompt live on the server, so the relay never falls behind it. See MCP server.

Piping and scripting

Output is plain text, one item per line, so it works with the usual tools.

Find the failed requests across recent recordings that had problems:

faylee list --problems --since 2026-09-24T00:00:00Z \
  | awk '{print $1}' \
  | while read id; do echo "== $id"; faylee network "$id" --failed; done

Find where an error first appears:

faylee console https://app.faylee.app/s/AbC123xYz0 --errors | head -n 5

Hand a recording to a model in one go:

faylee evidence AbC123xYz0 > evidence.txt

Look at the screen when the first request failed:

faylee network AbC123xYz0 --failed
faylee frames AbC123xYz0 --at 81500,82000 --size large

When a command fails because of a missing variable, a bad argument or an answer from Faylee, it prints the reason and exits with status 1.