golid / rules

---
description: Common CLI commands for development, deployment, debugging, and GCP operations
globs: scripts/*,Makefile,config/.env*
alwaysApply: false
---

# Common Commands

> **Thesis:** Shared commands should be discoverable, copy-safe, and tied to current project scripts so agents do not invent risky shell invocations.

This is an activation rule, not the command catalog. When a task needs a
concrete command for local development, deployment, debugging, GCP, Git,
tests, builds, migrations, or contract validation, read `docs/cli-reference.md`
and use the project-specific command there instead of inventing an equivalent
shell snippet.

## Command Selection Protocol

1. **Read the catalog first.** If the task is nontrivial shell work, check
   `docs/cli-reference.md` before running commands.
2. **Run the known-good command exactly, from the documented directory.** Do
   not substitute nearby tools (`npx` package names, alternate test flags,
   one-off scripts) unless the known command fails.
3. **One failure → diagnose, don't probe.** If a known command fails, inspect
   the concrete error and either fix that cause or report the blocker. Do not
   try a chain of equivalent commands hoping one works.
4. **Prefer compile/smoke checks when full commands are unsafe.** For example,
   compile integration-tagged packages with `go test -tags=integration ... -run
   '^$'` when `TEST_DATABASE_URL` is not confirmed safe.
5. **Tell the user what was not run.** If a command is skipped because it is
   destructive, unavailable, or environment-dependent, say so in the closeout.

## When to Use

- Starting or debugging local services.
- Running tests, builds, migrations, or seed commands.
- Inspecting GCP logs, secrets, deploy status, or storage.
- Running webhook or external API test commands.
- Checking what needs to be pushed.
- Validating generated contracts such as `backend/openapi.yaml`.

## Known Command Pitfalls

| Do Not Use | Use Instead | Why |
|---|---|---|
| `python` | `python3` | The dev container does not provide `python`; repeated probes waste time. |
| `grep`, `find`, `cat`, `head`, `tail` | Cursor tools: `rg`, `Glob`, `ReadFile` | Tooling rules already provide safer, faster search/read paths. |
| `npx --yes @apidevtools/swagger-cli ...` | `npm run generate:types` from `frontend/`, or a repo-local parser if type generation is too heavy | `npx` can fail in Cursor's server path; generated API types are the contract smoke test this repo already uses. |
| `go test -tags=integration ...` without checking env | Untagged `go test`, or `go test -tags=integration <pkg> -run '^$'` for compile-only, unless `TEST_DATABASE_URL` is confirmed safe | Integration tests can wipe the dev DB. |
| `git add -A` | Stage explicit files | Avoid sweeping unrelated user changes into commits. |

## Reference

Use `docs/cli-reference.md`.