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

# Quick Start

> First snapshot in under 5 minutes using local execution

This guide walks you through creating your first production-realistic snapshot using **local execution**. Perfect for getting started quickly without deploying infrastructure.

## What You'll Accomplish

By the end of this guide, you'll have:

* ✅ A `basecut.yml` configuration file tailored to your database schema
* ✅ A production-realistic snapshot with anonymized PII
* ✅ A restored snapshot in your local development database
* ✅ Understanding of the `init` → `snapshot create` → `snapshot restore` workflow

<Info>
  **For production**: After completing this guide, see [Self-Hosted
  Agents](/advanced/agent-deployment) for the recommended production deployment.
</Info>

## Prerequisites

* PostgreSQL database (12+) with some data
* Database accessible from your local machine (localhost or network-accessible)

***

## Step 1: Install CLI

Install the Basecut CLI:

```bash theme={null}
curl -fsSL https://basecut.dev/install.sh | sh
basecut --version
```

**Success indicator**: `basecut version x.y.z`

***

## Step 2: Authenticate

Create a Basecut account and authenticate:

```bash theme={null}
basecut login
```

This opens your browser for authentication. Once complete, your credentials are stored locally.

**Success indicator**: `✓ Authenticated as you@example.com`

***

## Step 3: Generate Configuration

Point Basecut at your database to auto-detect schema and relationships:

```bash theme={null}
basecut init --source "postgresql://user:pass@localhost:5432/myapp"
```

**What `init` does automatically:**

The `init` command does the heavy lifting for you:

* 🔍 **Schema detection**: Analyzes all tables, columns, and data types
* 🔗 **FK analysis**: Maps foreign key relationships to build the dependency graph
* 🎯 **Root table suggestions**: Identifies good starting points (tables with many incoming FKs)
* 🔄 **Cycle detection**: Finds and handles circular relationships
* 🛡️ **PII detection**: Auto-detects common PII patterns (emails, phones, names, etc.)
* 📝 **Config generation**: Creates a ready-to-use `basecut.yml` with sensible defaults

This creates `basecut.yml` in your current directory with:

* Detected tables and foreign key relationships
* Suggested root tables and FK connectivity details
* Optional PII anonymization rules (email, phone, etc.)

Want to tune masking behavior before your first restore? See
[Anonymization](/configuration/anonymization) for `auto`, `manual`, and
org-level policy options.

**Success indicator**: `✓ Created basecut.yml with 42 tables detected`

<Tip>
  **Troubleshooting `init`**: If you see connection errors, verify your database
  is accessible and the connection string format is correct
  (`postgresql://user:pass@host:port/dbname`). For SSH tunnels or complex
  setups, ensure the database is reachable from your local machine.
</Tip>

<Accordion title="Example generated basecut.yml">
  ```yaml theme={null}
  # Auto-generated by basecut init
  version: "1"
  name: "my-snapshot"

  from:
    - table: users
      where: 'created_at > :since'
      params:
        since: '2024-01-01'

  traverse:
    parents: 10 # Follow parent relationships
    children: 2 # Follow child relationships

  limits:
    rows:
      per_table: 1000 # Max rows per table
      total: 100000 # Max total rows

  anonymize:
    mode: auto

  output: ./snapshots
  ```
</Accordion>

***

## Step 4: Create a Snapshot (Local Execution)

Run the extraction locally (default):

```bash theme={null}
basecut snapshot create \
  --config basecut.yml \
  --name "my-first-snapshot" \
  --source "postgresql://localhost:5432/myapp_dev"
```

**What's happening:**

1. CLI reads your `basecut.yml` configuration
2. Connects directly to your database from your machine
3. Follows foreign keys from root tables to extract related data
4. Applies anonymization rules to PII fields
5. Stores snapshot on your local filesystem

**Success indicator**:

```
⣾ Extracting... (0/42 tables)
✓ Extracted 2,847 rows across 23 tables
✓ Anonymized 312 PII fields
✓ Snapshot written to local output path: ./snapshots
```

<Tip>
  **Local is the default.** Omit `--async` to run extraction on your machine
  without agent infrastructure.
</Tip>

***

## Step 5: Restore the Snapshot

Apply the extracted data to a different database (or the same one for testing):

```bash theme={null}
basecut snapshot restore my-first-snapshot:latest \
  --target "postgresql://localhost:5432/myapp_test"
```

**What's happening:**

1. CLI reads snapshot from storage
2. Validates target schema compatibility
3. Inserts data in dependency order (respects foreign keys)
4. Reports completion

<Info>Run migrations first. Restore does not create or alter tables.</Info>

**Success indicator**:

```
✓ Loading snapshot: my-first-snapshot:latest
✓ Validated schema for 23 tables
✓ Inserted 2,847 rows
✓ Verified referential integrity
✓ Restore complete in 3.2s
```

<Check>
  Your local database now has a production-realistic subset with all PII safely
  anonymized.
</Check>

***

## Common Next Steps

Now that you've created your first snapshot, here's what to explore next:

<CardGroup cols={2}>
  <Card title="Anonymization" icon="mask" href="/configuration/anonymization">
    Add domain-specific PII protection rules and fine-tune anonymization
    strategies
  </Card>

  <Card title="Set Up CI/CD" icon="webhook" href="/workflows/ci-cd">
    Automate snapshot creation and restore in your CI pipeline for consistent
    test data
  </Card>

  <Card title="Deploy Agents for Production" icon="server" href="/advanced/agent-deployment">
    Run snapshot extraction inside your VPC for production databases (TEAM plan)
  </Card>

  <Card title="Explore Workflows" icon="diagram-project" href="/workflows/common-workflows">
    Learn patterns for debugging, testing migrations, and sharing data with
    partners
  </Card>
</CardGroup>

***

## Verify the Data

Check what was restored:

```sql theme={null}
-- See available tables
\dt

-- Count rows
SELECT
  relname AS table_name,
  n_live_tup::bigint AS estimated_rows
FROM pg_stat_user_tables
ORDER BY estimated_rows DESC;

-- Verify anonymization worked
SELECT email, phone FROM users LIMIT 5;
-- email                    | phone
-- ------------------------ | -------------
-- jane.doe42@example.com   | 555-0192
-- john.smith7@example.com  | 555-0847
```

***

## Ready for Production?

You just completed a **local execution** quick start. For production workloads, deploy self-hosted agents:

<CardGroup cols={3}>
  <Card title="Deploy on Railway" icon="rocket" href="/advanced/agent-deployment#railway-fastest" color="#ea5a0c">
    One-click managed deployment for a production-ready Basecut agent
  </Card>

  <Card title="Deploy Self-Hosted Agents" icon="server" href="/advanced/agent-deployment" color="#ea5a0c">
    **Next step for production**: Deploy agents in Docker/Kubernetes
    (recommended)
  </Card>

  <Card title="Execution Modes" icon="bolt" href="/core-concepts/execution-modes">
    Understand agent vs local execution and when to use each
  </Card>
</CardGroup>

***

## Customize Your Setup

<CardGroup cols={2}>
  <Card title="Snapshot Rules" icon="mask" href="/configuration/snapshot-rules">
    Add custom PII protection for your domain-specific fields
  </Card>

  <Card title="YAML Configuration" icon="file-code" href="/configuration/yaml-reference">
    Fine-tune extraction depth, limits, and filters
  </Card>

  <Card title="CI/CD Integration" icon="webhook" href="/workflows/ci-cd">
    Automate snapshot creation in GitHub Actions
  </Card>

  <Card title="Common Workflows" icon="diagram-project" href="/workflows/common-workflows">
    Patterns for testing, debugging, and data sharing
  </Card>
</CardGroup>