---
title: Recording
description: Starting, stopping, and pausing the daemon, checking status, and the lifecycle of stored data.
---

Recording is done by a background daemon (a launchd agent). Everything is controlled with short commands:

| Command | Effect |
| --- | --- |
| `tadoru start` | Register with launchd and start background recording |
| `tadoru stop` | Stop recording and unregister from launchd (**data is kept**) |
| `tadoru pause --for 30m` | Pause; without `--for`, pauses indefinitely until `resume` |
| `tadoru resume` | Resume from pause |
| `tadoru status` | Check daemon state, event counts, and store info |

## Starting

```bash
tadoru start
```

On startup, permissions are checked. If any are missing, recording **does not start** and the command exits with code 3 explaining what to grant (see the [permissions guide](/guides/permissions)).

### Running in the foreground

Two ways to observe what's happening without daemonizing:

```bash
tadoru start --foreground   # same configuration as the daemon, in the foreground (dev/debug)
tadoru record --stream      # stream raw events as NDJSON to stdout
```

`record` is designed for piping and experimentation; use `--out events.jsonl` to write to a file. For everyday recording, use `start`.

## Checking status

```bash
tadoru status
tadoru status --json   # for agents and scripts
```

```json
{
  "running": true,
  "paused": false,
  "since": "2026-08-16T08:00:00Z",
  "uptime_s": 3600,
  "events_captured": 12345,
  "last_event_ts": "2026-08-16T08:59:58Z",
  "store": { "path": "~/.local/state/tadoru/store.sqlite", "size_bytes": 5242880, "retention_hours": 48, "oldest_event_ts": "2026-08-14T09:00:00Z" },
  "capture": { "sources": ["app", "window", "ui", "input", "browser"], "text_content": false },
  "permissions_ok": true
}
```

When there is no daemon to act on (`status`, `stop`, etc.), the exit code is 4.

## Pausing and resuming

`pause` is handy when you want recording off just for a meeting, a screen share, or a sensitive task:

```bash
tadoru pause --for 30m   # resumes automatically after 30 minutes
tadoru pause             # paused until you resume
tadoru resume
```

:::tip
If you want certain apps or sites permanently excluded rather than temporarily paused, use [filters](/guides/filters) — they discard matching events before anything is written to the store.
:::

## Data lifecycle

- Data lives only in the local SQLite store at `~/.local/state/tadoru/store.sqlite` (override with `--store`).
- Events older than **48 hours** are deleted automatically by default (`retention_hours`, see [configuration](/reference/config)).
- To delete manually, use `purge`:

```bash
tadoru purge --before 24h   # delete events older than 24 hours
tadoru purge --all          # delete everything (with a confirmation prompt)
```

:::warning
`purge` is destructive. `--all` asks for confirmation (suppress with `--quiet`).
:::