Migration Plan

How existing shell scripts, pnpm tasks, and Make targets are progressively replaced by gl commands.

Migration Table

The full mapping from current tools to their gl equivalents:

Current Tool / Script	New `gl` Command	Strategy	Priority
`tools/scripts/setup.sh`	`gl setup`	Rewrite in Python (Click + Rich)	P1
`tools/scripts/health-check.sh`	`gl health`	Rewrite in Python (Click + Rich)	P1
`tools/scripts/gen-errors.py`	`gl codegen errors`	Wrap existing uv script invocation	P1
`tools/scripts/gen-types.sh`	`gl codegen types`	Wrap existing script, plan Python rewrite	P2
`tools/scripts/gen-openapi.sh`	`gl codegen openapi`	Wrap existing stub	P3
`tools/scripts/gldl.sh`	`gl download`	Delegate to `gospelib-download` entry point	P1
`tools/scripts/run-ingest.sh`	`gl ingest run`	Delegate to `gospelib-ingest` entry point	P1
`tools/scripts/db-migrate.sh`	`gl db migrate`	Wrap stub, implement when ready	P3
`pnpm dev:stack`	`gl dev start`	Call `docker compose` via subprocess	P1
`pnpm dev:stack:stop`	`gl dev stop`	Call `docker compose` via subprocess	P1
`pnpm dev:stack:logs`	`gl dev logs`	Call `docker compose` via subprocess	P1
`pnpm infra:up`	`gl infra up`	Call `docker compose` via subprocess	P1
`pnpm infra:down`	`gl infra down`	Call `docker compose` via subprocess	P1
`pnpm infra:reset`	`gl infra reset`	Call `docker compose` via subprocess	P1
`pnpm infra:logs`	`gl infra logs`	Call `docker compose` via subprocess	P2
`pnpm test`	`gl test run`	Call `nx affected -t test` via subprocess	P1
`pnpm lint`	`gl lint run`	Call `nx affected -t lint` via subprocess	P1
`pnpm format`	`gl format run`	Call `prettier --write .` via subprocess	P2
`pnpm format:check`	`gl format check`	Call `prettier --check .` via subprocess	P2
`pnpm typecheck`	`gl lint typecheck`	Call `nx run-many -t typecheck`	P2
`pnpm codegen:errors`	`gl codegen errors`	Call `uv run --script gen-errors.py`	P1
`pnpm codegen:errors:check`	`gl codegen errors --check`	Call with `--check` flag	P1
`make help`	`gl --help`	Superseded by `gl` help system	P1

Backward Compatibility

Existing workflows must keep working

No existing workflow should break during migration. The gl commands are additive — old tools are deprecated, not deleted.

The rules:

Existing pnpm scripts, make targets, and VS Code tasks continue to work throughout migration
Bash scripts in tools/scripts/ are not deleted until gl equivalents are verified and stable
Deprecated scripts print a warning: ⚠ This script is deprecated. Use "gl <command>" instead.
The Makefile is updated to delegate to gl where possible

Migration Phases

Phased rollout

Migration happens in three phases, starting with the most-used developer workflows.

Phase	Priority	Command Groups
Phase 1	P1	`dev`, `infra`, `health`, `download`, `codegen errors`
Phase 2	P2	`test`, `lint`, `format`, `ingest`, `setup`
Phase 3	P3	`db`, `codegen openapi`, `codegen types`, `config`, `doctor`

Terminal Mockups

These examples show the intended output for key commands. They serve as visual specifications for implementers.

`gl dev start` — Starting the Full Stack

$ gl dev start

╭──────────── GospeLib Dev Stack ────────────╮
│ Starting all services + infrastructure...  │
╰────────────────────────────────────────────╯

  Infrastructure
    ✓ FalkorDB (6379)               ready    0.8s
    ✓ PostgreSQL (5432)             ready    1.2s
    ✓ Redis (6380)                  ready    0.4s
    ✓ Typesense (8108)              ready    1.5s

  Services
    ✓ Gateway (8080)                running  2.1s
    ✓ Content (8100)                running  3.4s
    ✓ Auth (8200)                   running  1.8s
    ✓ Billing (8300)                running  1.6s
    ✓ AI (8400)                     running  3.8s
    ✓ Notifications (8500)          running  1.5s

  Apps
    ✓ Web (3002)                    running  4.2s
    ✓ Admin (3001)                  running  3.9s

✓ Full stack running — 12/12 services ready (8.3s)

`gl test run` — Running Tests for a Service

$ gl test run --stack python --service content

  Running pytest for content service...

  services/content/tests/unit/test_models.py       ✓  12 passed     0.3s
  services/content/tests/unit/test_routes.py       ✓   8 passed     0.5s
  services/content/tests/unit/test_graph.py        ✓  15 passed     0.8s
  services/content/tests/integration/test_api.py   ✓   6 passed     2.1s

  ────────────────────────────────────────────
  Total: 41 passed, 0 failed, 0 skipped (3.7s)
  Coverage: 87.3%

`gl codegen errors --check` — Checking Generated Errors

$ gl codegen errors --check

  Checking generated error definitions against data/error-catalog.yaml...

  services/gateway/internal/errors/errors.go       ✓ up to date
  services/auth/internal/errors/errors.go          ✓ up to date
  services/billing/internal/errors/errors.go       ✗ outdated
  services/content/src/gospelib_content/errors.py  ✓ up to date
  services/ai/src/gospelib_ai/errors.py            ✓ up to date

✗ Error: 1 file is out of date.

  Run gl codegen errors to regenerate.

Exit code: 12

`gl download run --dry-run` — Dry Run Preview

$ gl download run --driver stepbible --dry-run

  Dry run — no files will be written.

  Driver: STEPBible-Data
  Phase: 1
  License: CC BY 4.0
  Datasets: 10

  Would fetch:
    → TOTHT — Translators OT Hebrew Tagger    (TSV, ~2.4 MB)
    → TAGNT — Translators Annotated GNT        (TSV, ~1.8 MB)
    → TIPNR — Translators Incidental Proper Names  (TSV, ~340 KB)
    ...7 more

  Would write:
    → data/corpus/gen.json          (merge 3 new fields)
    → data/corpus/exod.json         (merge 3 new fields)
    → data/lexicon/H0001-H1000.json (create)
    ...

  Total: 10 datasets, ~8.2 MB fetch, ~45 files affected

✓ Dry run complete — no changes made.

`gl health` — Service Health Check

$ gl health

╭────────────── Service Health ──────────────╮
│                                            │
│  Services                                  │
│    ✓ Gateway          8080   healthy       │
│    ✓ Content          8100   healthy       │
│    ✓ Auth             8200   healthy       │
│    ✗ Billing          8300   unreachable   │
│    ✓ AI               8400   healthy       │
│    ✓ Notifications    8500   healthy       │
│                                            │
│  Data Stores                               │
│    ✓ FalkorDB         6379   ready         │
│    ✓ PostgreSQL       5432   ready         │
│    ✓ Redis            6380   ready         │
│    ✓ Typesense        8108   ready         │
│                                            │
│  Summary: 9/10 healthy                     │
│  ⚠ Billing (8300) is unreachable           │
│                                            │
╰────────────────────────────────────────────╯

`gl dev status --output json` — Machine-Readable Output

{
  "data": [
    {
      "name": "gateway",
      "type": "service",
      "port": 8080,
      "status": "running",
      "pid": 12345,
      "uptime": "2h 15m"
    },
    {
      "name": "content",
      "type": "service",
      "port": 8100,
      "status": "running",
      "pid": 12346,
      "uptime": "2h 15m"
    }
  ],
  "meta": {
    "total": 12,
    "healthy": 11,
    "timestamp": "2026-03-16T14:30:00Z"
  }
}

`gl doctor` — Environment Diagnostics

$ gl doctor

╭────────────── Environment Check ──────────────╮
│                                               │
│  Prerequisites                                │
│    ✓ Node.js         v22.5.0    (>=22)        │
│    ✓ pnpm            9.15.0     (=9.15.0)     │
│    ✓ Go              1.23.4     (>=1.23)      │
│    ✓ Python          3.12.8     (>=3.12)      │
│    ✓ uv              0.5.14     (installed)    │
│    ✓ Docker          27.4.0     (running)     │
│    ✓ git             2.47.0     (installed)    │
│    ✗ golangci-lint   not found                │
│                                               │
│  Workspace                                    │
│    ✓ pnpm install       up to date            │
│    ✓ uv sync (content)  up to date            │
│    ✓ uv sync (ai)       up to date            │
│    ✓ uv sync (ingest)   up to date            │
│    ⚠ go mod (gateway)   outdated              │
│    ✓ .env.local         exists                │
│                                               │
│  Issues Found: 2                              │
│    ✗ golangci-lint is not installed.           │
│      Hint: Run "curl -sSfL https://..."       │
│    ⚠ go.sum outdated in services/gateway.     │
│      Hint: Run "cd services/gateway &&        │
│             go mod download"                  │
│                                               │
╰───────────────────────────────────────────────╯

Migration Table​

Backward Compatibility​

Migration Phases​

Terminal Mockups​

gl dev start — Starting the Full Stack​

gl test run — Running Tests for a Service​

gl codegen errors --check — Checking Generated Errors​

gl download run --dry-run — Dry Run Preview​

gl health — Service Health Check​

gl dev status --output json — Machine-Readable Output​

gl doctor — Environment Diagnostics​