> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tekma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Record a desktop source with the CLI

> List native displays or windows, record a foreground source, and keep a local recovery file when upload fails.

The desktop recorder captures native pixels, not browser diagnostics. It is useful for a browser plus another app, a native window, or a demonstration where tab capture is too narrow.

## Check available sources

```bash theme={null}
tekma record displays
tekma record windows
```

Use the returned exact display ID or window ID in the next command. You can select one source with `--display`, `--window-id`, `--app`, `--pid`, or (on macOS) `--bundle-id`; do not combine selectors. A window must be visible and uncovered on Linux X11.

## Record for a fixed duration

Authenticate with `captures:record` and provide a context URL for an OAuth upload:

```bash theme={null}
export CAPTURE_MCP_URL=https://mcp.tekma.dev/mcp
tekma auth login --scope captures:record
tekma record desktop --display DISPLAY_ID \
  --duration-seconds 90 \
  --url https://example.com/checkout \
  --title "Checkout with native payment dialog"
```

The duration is 1–1,800 seconds and defaults to 60. The URL records provenance; it does not claim that the native recording visited that page. Keep the selected source in the foreground. Stop earlier with Ctrl-C; the recorder finalizes the video and preserves the child command's exit result when a command is supervised.

## Stop manually or supervise a command

For a standalone recording with no timer, use `--until-stopped` and press Ctrl-C once to finalize. Do not combine it with a child command. To record while a process runs, pass the executable after `--` and keep a duration:

```bash theme={null}
tekma record desktop --app "Calculator" --duration-seconds 60 --local -- open -a Calculator
```

The child output goes to stderr. A second interrupt cancels a pending upload. `--speedup` can shorten runs of identical pixels longer than two seconds, retaining a half-second around each static run; it is off by default.

## Local mode, platforms, and limits

Add `--local` to retain a WebM and receipt without authentication or upload. OAuth uploads can include a title, description and folder; recording-link uploads use the owner's destination and do not accept those metadata flags. macOS supports native displays and macOS 15+ isolated windows with Screen Recording permission. Linux support is local X11; Wayland and Windows are not promised. There is no pixel redaction, browser diagnostics, or audio guarantee in the desktop output. Review the saved pixels before sharing.

If source discovery is empty, grant operating-system Screen Recording permission and restart the terminal. If finalization fails, inspect the retained local directory reported by the command before retrying. Run `tekma record desktop --help` for the installed release's complete flags.