---
title: "The faylee CLI"
description: "Read Faylee recordings from a terminal or a script with the faylee command, and relay Faylee's MCP server to agents that only run local commands."
canonical: https://faylee.app/docs/agents/cli
---

# 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`:

```bash
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.

```bash
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**.

:::caution
A personal token can do whatever you can do in Faylee. Keep it out of shell history you share, dotfiles you publish and repositories.
:::

## 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.

```bash
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

```bash
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

```bash
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

```bash
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

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

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

### network

```bash
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

```bash
faylee request <link> <id>
```

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

```bash
faylee request AbC123xYz0 42
```

### steps

```bash
faylee steps <link>
```

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

### chapters

```bash
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

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

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

### transcript

```bash
faylee transcript <link>
```

What the reporter said while recording, with times.

### frames

```bash
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

```bash
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](https://faylee.app/docs/support/recording-links.md).

| 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](https://faylee.app/docs/integrations/help-desks.md). |
| `--days <n>` | How many days the link works |

### mcp

```bash
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:

```bash
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](https://faylee.app/docs/agents/mcp.md).

## 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:

```bash
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:

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

Hand a recording to a model in one go:

```bash
faylee evidence AbC123xYz0 > evidence.txt
```

Look at the screen when the first request failed:

```bash
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.

## Related

- [MCP server](https://faylee.app/docs/agents/mcp.md)
- [MCP tools reference](https://faylee.app/docs/agents/tools.md)