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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.