# struere pull

> Pull remote resources to local files

The `pull` command downloads the current remote state from Convex and writes it to local files, creating or updating resource definitions in your project directories.

## Usage

```bash
bunx struere pull
bunx struere pull --force
bunx struere pull --env production
bunx struere pull --dry-run
bunx struere pull --json
```

## Flags

| Flag | Description |
|------|-------------|
| `--force` | Overwrite existing local files |
| `--env <environment>` | Environment to pull from (`development` or `production`, defaults to `development`) |
| `--dry-run` | Show what would be written without writing any files |
| `--json` | Output results as JSON |

## What It Does

The `pull` command:

1. Fetches the current state of all resources from your Convex backend for the specified environment
2. Generates local definition files for each resource
3. Writes the files to the appropriate directories

## Pulled Resources

| Resource | Directory | File Pattern |
|----------|-----------|-------------|
| Agents | `agents/` | `agents/{slug}.ts` |
| Data Types | `entity-types/` | `entity-types/{slug}.ts` |
| Roles | `roles/` | `roles/{name}.ts` |
| Automations | `triggers/` | `triggers/{slug}.ts` |
| Routers | `routers/` | `routers/{slug}.ts` |
| Custom Tools | `tools/` | `tools/index.ts` |

Index files (`index.ts`) are generated for each directory that has resources.

## When to Use Pull

The `pull` command is useful when:

- **Resources were created via the dashboard** — If you or a team member created agents, data types, roles, or automations through the web dashboard, `pull` brings those definitions into your local project so they can be managed as code.

- **Onboarding to an existing project** — When joining a team that already has resources configured in Convex, `pull` gives you the local files to start working with.

- **Recovering local files** — If local files were accidentally deleted or corrupted, `pull` restores them from the remote state.

- **Switching machines** — When setting up a new development environment, `pull` populates your project with the current remote definitions.

- **Pulling production state** — Use `--env production` to pull production configurations locally for review or comparison.

## Example Workflow

A common scenario is creating resources in the dashboard and then pulling them locally for version control:

```bash
bunx struere pull

git add agents/ entity-types/ roles/ triggers/ routers/ tools/
git commit -m "Pull remote resources to local definitions"
```

After pulling, you can modify the local files and use `struere dev` to sync changes back.

## Relationship with Dev and Status

| Command | Direction | Purpose |
|---------|-----------|---------|
| `struere pull` | Remote to local | Download remote state as local files |
| `struere dev` | Local to remote | Sync local files to remote |
| `struere status` | Comparison | Show differences without changing anything |

A typical workflow might be:

1. `struere pull` — Get the latest remote state
2. Edit local files — Make your changes
3. `struere status` — Review what will change
4. `struere dev` — Sync changes to the development environment