> For the complete documentation index, see [llms.txt](https://gyrinx.gitbook.io/gyrinx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gyrinx.gitbook.io/gyrinx/how-to-guides/useful-scripts.md).

# Useful Scripts

This document provides an overview of commonly used scripts in the Gyrinx project.

## Development Scripts

### `scripts/dev.sh`

Starts the full development environment with a single command. Handles per-worktree database isolation automatically: ensures the database exists (forking from the `gyrinx_main` template if needed), runs migrations, starts Django `runserver` and `npm run watch` for CSS rebuilds.

```bash
./scripts/dev.sh              # Normal startup
./scripts/dev.sh --no-watch   # Skip CSS watcher
./scripts/dev.sh --reset-db   # Drop and re-fork the worktree database
```

### `scripts/setup-local-postgres.sh`

One-time setup: installs PostgreSQL 16 and pgAdmin via Homebrew, initialises the database cluster with ICU collation (matching Linux/production sort behaviour), and creates the `gyrinx_main` development database. If Docker Postgres is running, it dumps and restores from it automatically.

```bash
./scripts/setup-local-postgres.sh
```

### `scripts/fmt.sh`

Formats all code in the project including Python, JavaScript, SCSS, and Django templates.

```bash
./scripts/fmt.sh
```

### `scripts/test.sh`

Thin wrapper over `pytest` against the local Postgres database. `pyproject.toml` already enables parallel execution (`-n auto`) and `--nomigrations` via addopts, so the bare invocation runs the full suite in parallel and rebuilds the test DB from current model definitions on every run.

```bash
./scripts/test.sh                  # full suite, parallel
./scripts/test.sh -n 0             # serial
./scripts/test.sh n23/core/     # a directory
./scripts/test.sh -k campaign      # by name
```

### `scripts/check_migrations.sh`

Checks for any migration issues or conflicts.

```bash
./scripts/check_migrations.sh
```

## Database Scripts

### `scripts/cleanup-worktree-dbs.sh`

Finds and removes orphaned worktree databases (from deleted worktrees) along with their pytest test databases. Pass `--include-tests` to also clean up test DBs for *active* worktrees — pytest will recreate them on next run, so this is a safe way to reclaim disk.

```bash
./scripts/cleanup-worktree-dbs.sh                   # Dry run: orphans only
./scripts/cleanup-worktree-dbs.sh --force           # Drop orphans
./scripts/cleanup-worktree-dbs.sh --include-tests   # Dry run + active test DBs
./scripts/cleanup-worktree-dbs.sh --include-tests --force
```

### `scripts/reset-migrations-to-main.sh`

Safely resets Django migration state to match the main branch. Useful when switching between branches with different migration histories.

```bash
./scripts/reset-migrations-to-main.sh
```

## Quality Assurance Scripts

### `scripts/fmt-check.sh`

Checks if code formatting is correct without making changes.

```bash
./scripts/fmt-check.sh
```

## Management Commands

These are Django management commands available through the `manage` command:

### `manage setupenv`

Sets up the development environment file (.env).

```bash
manage setupenv
```

### `manage ensuresuperuser`

Ensures a superuser exists for development.

```bash
manage ensuresuperuser
```

### `manage loaddata_overwrite`

Loads Django fixtures with overwrite capability. Run `manage migrate` first: the fixture was dumped from production's schema, so the database must be at least as new before loading.

```bash
manage migrate
manage loaddata_overwrite <fixture_name>
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gyrinx.gitbook.io/gyrinx/how-to-guides/useful-scripts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.