Record

# record CLI

A macOS command-line tool for recording audio, screen, and camera output. Designed for both human users and AI agents operating in a terminal.

Output file paths are printed to **stdout**. Status messages go to **stderr**, making the tool pipeline-friendly.

## IMPORTANT: User Consent Required

**Always ask the user for explicit permission before running any recording command.** Recording audio (microphone), screen, or camera captures sensitive data and may be unexpected. Before executing `record audio`, `record screen`, or `record camera`, confirm with the user that they intend to record, what will be captured, and the duration. Listing devices (`--list-devices`, `--list-displays`, `--list-windows`, `--list-cameras`) and taking screenshots (`--screenshot`) are less intrusive but should still be confirmed if not explicitly requested.

## Installation

```bash
brew install atacan/tap/record
```

## Quick Reference

```bash
# Audio
record audio --duration 10                    # Record 10s of audio
record audio --duration 5 --json              # JSON output with file path

# Screen
record screen --duration 5                    # Record screen for 5s
record screen --screenshot                    # Take a screenshot
record screen --screenshot --output /tmp/s.png

# Camera
record camera --duration 5                    # Record webcam for 5s
record camera --photo                         # Take a photo
```

## Subcommands

| Subcommand | Purpose |
|---|---|
| `record audio` | Record from microphone |
| `record screen` | Record screen video or take a screenshot |
| `record camera` | Record from webcam or take a photo |

Each subcommand has its own `--help` flag with full option details.

## Key Patterns for AI Agents

### Get the output file path

The tool prints the output file path to stdout. Capture it:

```bash
FILE=$(record audio --duration 5)
echo "Recorded to: $FILE"
```

### Use --json for structured output

All subcommands support `--json` to emit mac...