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

# basecut snapshot create

> Create a sanitized snapshot from a source database

Create a snapshot from your config and source database.

Authentication is required. `basecut snapshot create` always needs an API key before extraction starts. Provide it with `--api-key`, `BASECUT_API_KEY`, or a saved profile from `basecut login`.

## Usage

```bash theme={null}
basecut snapshot create --config <path> [flags]
```

## Flags

| Flag                           | Required | Description                                                                                                                                                                  |
| ------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--config <path>, -c`          | Yes      | Path to `basecut.yml`.                                                                                                                                                       |
| `--name <string>, -n`          | No       | Snapshot name. Must be provided via `--name` or `name` in config.                                                                                                            |
| `--source <url>, -s`           | Local    | Source connection string for local execution. Required whenever the command runs locally (the default). Optional only when using `--async` with a non-local output provider. |
| `--connect-timeout <duration>` | `10s`    | Timeout for initial source DB connection in local mode (for example `5s`, `30s`).                                                                                            |
| `--async`                      | No       | Queue for agent execution (TEAM plan). Ignored when output provider is `local` (for example `output: ./snapshots`), and the command runs locally instead.                    |
| `--tag <string>, -t`           | No       | Version tag.                                                                                                                                                                 |
| `--git`                        | No       | Attach git metadata.                                                                                                                                                         |
| `--profile <name>`             | No       | Credential profile used to resolve API key.                                                                                                                                  |
| `--api-key <key>`              | No       | API key override (otherwise uses `BASECUT_API_KEY` or the selected profile).                                                                                                 |

## Examples

### Basic Local Example

```bash theme={null}
basecut snapshot create \
  --config basecut.yml \
  --source "$DATABASE_URL" \
  --name "dev-seed"
```

### Agent Example

```bash theme={null}
basecut snapshot create \
  --config basecut.yml \
  --name "nightly-seed" \
  --async
```

`--async` only queues an agent job when the config output provider is non-local. If your config uses local output (for example `output: ./snapshots`), `--async` is ignored and local execution still requires `--source` or `BASECUT_DATABASE_URL`.

Track async job progress with:

```bash theme={null}
basecut snapshot status <job-id>
```

## Config Example

```yaml theme={null}
version: '1'
name: 'dev-seed'

from:
  - table: users
    where: 'id = :id'
    params:
      id: 1

traverse:
  parents: 10
  children: 2

limits:
  rows:
    per_table: 1000
    total: 100000

anonymize: auto
output: ./snapshots
```

See [YAML Reference](/configuration/yaml-reference) for full config options.