CLI Resources Reference¶
Reference ID: REF-CLI
Purpose: authoritative navigation map for command-line software used across the Bluefly engineering environment.
Scope: tells operators and agents which software owns which job, the base command to invoke it, where the authoritative documentation lives, and how Bluefly expects it to be used.
Source: rebuilt from the current cli-resources-reference.md, the Mac CLI inventory, and current upstream documentation.
This is an authority and discovery reference, not a frozen copy of upstream command help.
Command syntax changes. Before using unfamiliar flags or destructive operations, run the installed CLI's help or read the linked upstream documentation.
1. Operating Rules¶
1.1 Authority order¶
For command behavior, use this precedence:
- Current installed CLI help
- Current upstream documentation
- Current Bluefly engineering doctrine
- Repository-local integration documentation
- Historical notes or agent memory
For Gas City specifically:
CURRENT docs.gascity.com = semantic authority
installed `gc <command> --help` = executable command authority for this deployment
A command named on docs.gascity.com is not executable here unless it appears in the installed binary's help. Bluefly documentation may define when and why a CLI is used, but it should not redefine the upstream tool's syntax.
1.2 Bluefly execution rules¶
- GitLab is the source-control and CI authority.
- Oracle is the production/factory runtime authority.
- 1Password is the secret system of record and delivery mechanism.
- Gas City is the orchestration/control-plane authority.
- Beads is the durable work graph.
- Dolt is the database substrate where Beads/Gas City require it.
- DDEV is the default local Drupal execution environment.
- Composer is the Drupal/PHP dependency authority.
- Terraform/OpenTofu and governed IaC own infrastructure desired state.
- Tailscale is the private operator network.
- Cloudflare Tunnel is governed ingress where explicitly configured.
- Do not invent wrapper scripts merely to avoid learning an upstream CLI.
- Do not commit generated runtime state, credentials, sockets, caches, or machine-local bindings.
- Do not use a lower-level tool when a higher-level owning workflow already provides the operation.
1.3 Safety classifications¶
| Class | Meaning |
|---|---|
| READ | Inspection/query operations. Safe default. |
| WRITE | Changes source, work state, configuration, or remote resources. Requires correct scope. |
| RUNTIME | Starts/stops/restarts services, agents, containers, or infrastructure. |
| DESTRUCTIVE | Deletes, rewrites history/state, destroys infrastructure, or changes security authority. Verify first. |
| GOVERNED | Use only through the Bluefly-owned workflow or authority named in this document. |
2. Bluefly Core Command Set¶
These are the commands an operator or engineering agent should recognize first.
| Priority | Software | Base command | What it owns | Typical Bluefly use | Authority |
|---|---|---|---|---|---|
| P0 | Gas City | gc |
Agent orchestration, City lifecycle, Rigs, Packs, Formulas, Orders, Events, runtime diagnostics | Operate the Bluefly software factory | https://docs.gascity.com/ |
| P0 | Beads | bd |
Durable work, dependencies, status, work graph | Claim, inspect, update, and close durable work | https://beads.gascity.com/ |
| P0 | Git | git |
Repository source and history | Branch/worktree/commit operations | https://git-scm.com/docs |
| P0 | GitLab CLI | glab |
Merge requests, pipelines, issues, releases, project metadata | Governed GitLab delivery | https://docs.gitlab.com/cli/ |
| P0 | 1Password CLI | op |
Secret references and authenticated integrations | Reuse authenticated authority without exposing secret values | https://www.1password.dev/cli |
| P0 | Dolt | dolt |
Versioned SQL database operations | Low-level DB work only when owning Beads/Gas City workflow requires it | https://www.dolthub.com/docs/cli-reference/cli/ |
| P1 | DDEV | ddev |
Local containerized web-development environment | Drupal execution, services, DB, Drush, Composer | https://docs.ddev.com/en/stable/users/usage/cli/ |
| P1 | Composer | composer |
PHP packages and dependency graph | Drupal packages, Recipes, site-template dependency assembly | https://getcomposer.org/doc/03-cli.md |
| P1 | Drush | drush / ddev drush |
Drupal runtime administration | Cache, config, module, entity, and site operations | https://www.drush.org/ |
| P1 | OpenAI Codex CLI | codex |
AI coding-agent execution | Repository implementation/review work | https://developers.openai.com/codex/cli/ |
| P1 | Gemini CLI | gemini |
AI coding-agent execution | Secondary coding/research agent | https://github.com/google-gemini/gemini-cli |
| P1 | OpenClaw | openclaw |
Agent gateway/runtime integration | Bluefly gateway/runtime work | Project/upstream source |
| P1 | Tailscale | tailscale |
Private mesh networking | Oracle/NAS/operator connectivity | https://tailscale.com/docs/reference/tailscale-cli |
| P1 | Cloudflared | cloudflared |
Cloudflare Tunnel client | Governed private/public ingress | https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/ |
| P1 | Terraform | terraform |
Infrastructure as code | Existing Terraform-managed infrastructure | https://developer.hashicorp.com/terraform/cli |
| P1 | OpenTofu | tofu |
Open-source Terraform-compatible IaC | IaC where OpenTofu is the selected engine | https://opentofu.org/docs/cli/ |
| P1 | OCI CLI | oci |
Oracle Cloud API | Oracle Cloud inspection/operations when not already owned by IaC | https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm |
| P2 | tmux | tmux |
Persistent terminal multiplexing | Long-running operator/agent sessions | https://github.com/tmux/tmux/wiki |
| P2 | Docker | docker |
Container runtime | Local/runtime container inspection where approved | https://docs.docker.com/reference/cli/docker/ |
3. Gas City, Gas City, Beads, and Dolt¶
3.1 Gas City¶
Base command: gc
Gas City is the Bluefly orchestration layer. It orchestrates fleets of agents using six core primitives:
| Primitive | Meaning |
|---|---|
| Agent | WHO performs work |
| Bead | WHAT durable unit of work exists |
| Formula | HOW reusable work is performed |
| Rig | WHERE the external project/repository lives |
| Pack | CONFIGURES agents, formulas, orders, and behavior |
| Event | OBSERVE append-only runtime activity |
Orders trigger formulas but are not a seventh primitive.
Primary help:
gc --help
gc <command> --help
Durable operator classes live in blucity-operator-contract.md. Exact commands for this deployment are below. Re-verify after a gc upgrade. Do not copy this map into the factory operating contract.
3.1.1 Gas City capability map (gc 1.4.1)¶
PLATFORM_VERSION=gc 1.4.1
VERIFIED=YES
VERIFIED_AT=2026-09-10
DISCOVERY=`gc --help` and `gc <command> --help`
SEMANTIC_AUTHORITY=https://docs.gascity.com/
EXECUTABLE_AUTHORITY=installed binary help
On this version, gc ready is not a command. gc bead is not a command. Use gc beads / bd for Bead inspection and the Beads work loop. Do not store workstation paths, loopback ports, live Rig inventories, or temporary doctor failures in this map.
Classification uses the operator-contract classes: READ_ONLY, BOUNDED_WRITE, ADMIN_WRITE, DANGEROUS.
| CAPABILITY | CLI_COMMAND | READ_OR_WRITE | ROLE_ALLOWED |
|---|---|---|---|
| city status | gc status |
READ_ONLY | HUMAN_OPERATOR, AGENT |
| dashboard | gc dashboard |
READ_ONLY | HUMAN_OPERATOR, AGENT |
| config inspect | gc config show, gc config explain |
READ_ONLY | HUMAN_OPERATOR, AGENT |
| beads inspect | gc beads list, gc beads show, gc beads health |
READ_ONLY | HUMAN_OPERATOR, AGENT |
| convoy inspect | gc convoy list, gc convoy status, gc convoy stranded |
READ_ONLY | HUMAN_OPERATOR, AGENT |
| session inspect | gc session list, gc session logs, gc session peek |
READ_ONLY | HUMAN_OPERATOR, AGENT |
| rig inspect | gc rig list, gc rig status |
READ_ONLY | HUMAN_OPERATOR, AGENT |
| cost / reliability | gc costs, gc analyze |
READ_ONLY | HUMAN_OPERATOR, AGENT |
| events | gc events |
READ_ONLY | HUMAN_OPERATOR, AGENT |
| identity | gc whoami, gc version |
READ_ONLY | HUMAN_OPERATOR, AGENT |
| doctor diagnose | gc doctor (no --fix) |
READ_ONLY with possible runtime side effects | HUMAN_OPERATOR, AGENT |
| dispatch | gc sling |
BOUNDED_WRITE | AGENT; human may nudge |
| formula inspect / cook | gc formula show, gc formula cook, gc sling --formula |
READ_ONLY / BOUNDED_WRITE | HUMAN_OPERATOR, AGENT |
| GluLess prove (via pack check) | python -m gluless prove / pack scripts/gluless-check (env: GLULESS_CONTRACT, GLULESS_OPENAPI, GLULESS_BASE_URL) |
READ_ONLY proof / BOUNDED_WRITE when slung | AGENT; operator may run prove locally |
gc mail inbox, gc mail check, gc mail send |
READ_ONLY / BOUNDED_WRITE | HUMAN_OPERATOR, AGENT | |
| nudge | gc nudge, gc session nudge |
BOUNDED_WRITE | HUMAN_OPERATOR, AGENT |
| beads work (via Beads) | gc bd ... / bd ... |
BOUNDED_WRITE | AGENT |
| doctor repair | gc doctor --fix |
DANGEROUS | ADMIN; not normal human surface |
| runtime lifecycle | gc start, gc stop, gc restart, gc reload, gc suspend, gc resume |
ADMIN_WRITE | MAYOR / runtime authority |
| supervisor | gc supervisor ..., gc register, gc unregister |
ADMIN_WRITE | ADMIN |
| pack / import | gc pack ..., gc import ... |
ADMIN_WRITE | ADMIN; not normal human surface |
| rig mutation | gc rig add, gc rig remove, gc rig set-endpoint |
ADMIN_WRITE | ADMIN; not normal human surface |
| agent configuration | gc agent ..., gc prompt ..., gc prime |
ADMIN_WRITE | ADMIN; not normal human surface |
| beads topology | gc beads city ... |
ADMIN_WRITE | ADMIN; not normal human surface |
| Dolt / storage | gc maintenance, gc dolt-cleanup |
DANGEROUS | HARBORMASTER / storage authority |
API_METHOD and API_PATH for these capabilities: NOT_ESTABLISHED in this map. Discover from OpenAPI/schema when present. Do not guess.
Selected records in the operator-contract schema:
CAPABILITY=city-status
CLI_COMMAND=gc status
API_METHOD=NOT_ESTABLISHED
API_PATH=NOT_ESTABLISHED
READ_OR_WRITE=READ_ONLY
ROLE_ALLOWED=HUMAN_OPERATOR,AGENT
PLATFORM_VERSION=gc 1.4.1
VERIFIED=YES
VERIFIED_AT=2026-09-10
CAPABILITY=beads-inspect
CLI_COMMAND=gc beads list | gc beads show | gc beads health
API_METHOD=NOT_ESTABLISHED
API_PATH=NOT_ESTABLISHED
READ_OR_WRITE=READ_ONLY
ROLE_ALLOWED=HUMAN_OPERATOR,AGENT
PLATFORM_VERSION=gc 1.4.1
VERIFIED=YES
VERIFIED_AT=2026-09-10
CAPABILITY=dispatch-sling
CLI_COMMAND=gc sling
API_METHOD=NOT_ESTABLISHED
API_PATH=NOT_ESTABLISHED
READ_OR_WRITE=BOUNDED_WRITE
ROLE_ALLOWED=AGENT
PLATFORM_VERSION=gc 1.4.1
VERIFIED=YES
VERIFIED_AT=2026-09-10
CAPABILITY=doctor-diagnose
CLI_COMMAND=gc doctor
API_METHOD=NOT_ESTABLISHED
API_PATH=NOT_ESTABLISHED
READ_OR_WRITE=READ_ONLY
ROLE_ALLOWED=HUMAN_OPERATOR,AGENT
PLATFORM_VERSION=gc 1.4.1
VERIFIED=YES
VERIFIED_AT=2026-09-10
CAPABILITY=doctor-repair
CLI_COMMAND=gc doctor --fix
API_METHOD=NOT_ESTABLISHED
API_PATH=NOT_ESTABLISHED
READ_OR_WRITE=DANGEROUS
ROLE_ALLOWED=ADMIN
PLATFORM_VERSION=gc 1.4.1
VERIFIED=YES
VERIFIED_AT=2026-09-10
CAPABILITY=ready-work
CLI_COMMAND=ABSENT (gc ready is not an installed subcommand)
API_METHOD=NOT_ESTABLISHED
API_PATH=NOT_ESTABLISHED
READ_OR_WRITE=READ_ONLY
ROLE_ALLOWED=HUMAN_OPERATOR,AGENT
PLATFORM_VERSION=gc 1.4.1
VERIFIED=ABSENT
VERIFIED_AT=2026-09-10
CAPABILITY=ready-work: gc ready is not in installed gc --help Available Commands. gc ready --help returns root CLI help, not a ready command. Current docs that name gc ready are DOC_DRIFT on this binary. Discover ready-work from installed Beads / gc bd / gc beads help before encoding a substitute. gc convoy list is a real subcommand on this binary; it is not a ready replacement unless help proves that.
Bluefly rule: the authoritative City runs on Oracle. A workstation is a client/execution surface, not a second City authority. Live Rig counts, bindings, and provisioning results belong in Rig/catalog/deployment documentation, not in this command map.
Authority: https://docs.gascity.com/
3.2 Gas City¶
Base command: gt
Gas City is upstream multi-agent workspace tooling. Its CLI manages rigs, work, services, communication, agents, convoys, and diagnostics.
gt --help
| Area | Example command family | Purpose |
|---|---|---|
| Work | gt bead ..., gt close ..., gt done ... |
Work lifecycle |
| Convoys | gt convoy ... |
Track grouped work |
| Services | gt daemon ... |
Background runtime services |
| Workspace | gt ... workspace/rig commands |
Workspace topology |
| Diagnostics | gt ... diagnostic commands |
Inspect upstream runtime state |
Bluefly rule: do not treat legacy Gas City behavior as automatically authoritative over current Gas City behavior. Verify the current upstream command model first.
Authority: https://docs.gascityhall.ai/usage/
3.3 Beads¶
Primary base command: bd
Alternate installed command: beads
The inventory shows both bd and beads coming from the same Beads package. Treat them as one product, not two systems.
bd --help
| Capability | Purpose |
|---|---|
| Work records | Durable task/issue/work objects |
| Dependencies | Blocked/ready graph |
| Status | Open, in-progress, closed and related lifecycle |
| Query | Find ready work and inspect work state |
| Watch/event integration | Observe durable work changes |
| Diagnostics | Validate Beads repository/store assumptions |
Bluefly rule: Beads authority is Oracle. Do not create a second workstation-authoritative Beads/Dolt work graph.
Authority: https://beads.gascity.com/cli-reference
3.4 Dolt¶
Base command: dolt
Dolt is a SQL database with Git-like version-control semantics. It supports SQL, branches, commits, diffs, merges, remotes, and server operation.
dolt --help
| Capability | Command family |
|---|---|
| SQL | dolt sql ... |
| History | dolt log, dolt diff, dolt status |
| Branching | dolt branch, dolt checkout, dolt merge |
| Server | dolt sql-server ... |
| Remote/versioned DB | dolt remote, dolt push, dolt pull |
Bluefly rule: direct Dolt mutation is a lower-level operation. Prefer the owning Gas City/Beads workflow. Never run repair/migration commands simply because dolt or bd doctor suggests them without proving topology and authority first.
Authority: https://www.dolthub.com/docs/cli-reference/cli/
4. Source Control and GitLab¶
| Software | Base command | What it does | Bluefly use | Help / authority |
|---|---|---|---|---|
| Git | git |
Distributed source control | Source, branches, worktrees, commits, history | git help; https://git-scm.com/docs |
| GitLab CLI | glab |
GitLab terminal client | MRs, pipelines, issues, releases, metadata | glab help; https://docs.gitlab.com/cli/ |
| GitLab Runner | gitlab-runner |
Executes GitLab CI jobs | Self-hosted CI runtime | https://docs.gitlab.com/runner/ |
| Git LFS | git-lfs |
Large-file storage for Git | Only where a repository intentionally uses LFS | https://git-lfs.com/ |
| Git Town | git-town |
Higher-level Git workflow automation | Optional local workflow helper | https://www.git-town.com/ |
| git-filter-repo | git-filter-repo |
Rewrites Git history | Recovery/cleanup only | https://github.com/newren/git-filter-repo |
| BFG Repo-Cleaner | bfg |
Fast Git history cleanup | Exceptional repository remediation | https://rtyley.github.io/bfg-repo-cleaner/ |
| git-cliff | git-cliff |
Changelog generation | Release notes/changelog automation | https://git-cliff.org/ |
| Delta | delta |
Enhanced diff pager | Human-readable Git diffs | https://dandavison.github.io/delta/ |
| Entire | entire |
Git-aware development/session tooling | Optional development tooling | Upstream project docs |
| GitHub CLI | gh |
GitHub terminal client | Installed, but not Bluefly delivery authority | https://cli.github.com/manual/ |
Bluefly Git flow¶
feature/fix
-> merge request
-> release/v0.1.x
-> validated promotion merge request
-> main
Do not use gh to create a parallel Bluefly delivery workflow. Bluefly repositories and CI remain GitLab-native.
5. Authentication, Secrets, and Security¶
| Software | Base command | What it does | Bluefly policy | Authority |
|---|---|---|---|---|
| 1Password CLI | op |
Secret references, vault items, integrations | Primary secret authority | https://www.1password.dev/cli |
| SOPS | sops |
Encrypt/decrypt structured config | Use only where explicitly designed | https://getsops.io/ |
| age | age |
File encryption | Encryption primitive; not secret authority | https://age-encryption.org/ |
| Gitleaks | gitleaks |
Secret scanning | CI/local detection | https://gitleaks.io/ |
| TruffleHog | trufflehog |
Secret discovery | Deep scanning and incident response | https://trufflesecurity.com/trufflehog |
| Trivy | trivy |
Vulnerability/config/container/IaC scanning | Security pipeline tooling | https://trivy.dev/ |
| Semgrep | semgrep |
Static source/security analysis | SAST/policy analysis | https://semgrep.dev/docs/ |
| git-secrets | git-secrets |
Secret-pattern Git checks | Local guard only | https://github.com/awslabs/git-secrets |
| mkcert | mkcert |
Local trusted TLS certificates | Local development only | https://github.com/FiloSottile/mkcert |
| Vault | vault |
HashiCorp Vault client | Installed capability; not Bluefly secret system of record | https://developer.hashicorp.com/vault/docs/commands |
| sshpass | sshpass |
Non-interactive password injection to SSH | Avoid for governed Bluefly authentication | Upstream man page |
Bluefly secret law¶
AUTHENTICATE_ONCE=YES
SECRET_SYSTEM_OF_RECORD=1PASSWORD
SECRET_VALUES_IN_CHAT=NEVER
SECRET_VALUES_IN_SOURCE=NEVER
THOMAS_IS_CREDENTIAL_BROKER=NO
CUSTOM_SECRET_MANAGER=NO
Prefer secret references, official integrations, machine identities, workload identity, CI job tokens, OIDC, and target-native authorization over copied long-lived credentials.
6. Drupal and PHP¶
| Software | Base command | What it does | Bluefly use | Authority |
|---|---|---|---|---|
| DDEV | ddev |
Local containerized dev environment | Default Drupal local runtime | https://docs.ddev.com/ |
| Drush | drush or ddev drush |
Drupal administration CLI | Drupal runtime/config/entity operations | https://www.drush.org/ |
| Composer | composer |
PHP package/dependency manager | Drupal dependency authority | https://getcomposer.org/ |
| PHP | php |
PHP runtime | runtime/tool execution | https://www.php.net/manual/en/features.commandline.php |
| Phive | phive |
PHAR tool management | PHP toolchain management where used | https://phar.io/ |
Drupal command ownership order¶
When solving product functionality, evaluate in this order:
CORE
-> CONTRIB
-> CONFIGURATION
-> RECIPE
-> CANVAS / SDC
-> ECA / FLOWDROP
-> DRUPAL AI
-> TOOL API / MCP
-> EXISTING BLUEFLY EXTENSION
-> CUSTOM CODE ONLY AFTER A PROVEN GAP
Typical discovery¶
ddev --help
ddev describe
ddev drush --help
composer --help
composer show
Do not edit installed output under vendor/, web/core/, or web/modules/contrib/.
7. AI Coding and Agent Tools¶
| Software | Base command | What it does | Bluefly role | Authority |
|---|---|---|---|---|
| OpenAI Codex CLI | codex |
Repository coding agent | Implementation, review, bounded engineering tasks | https://developers.openai.com/codex/cli/ |
| Gemini CLI | gemini |
Terminal coding/AI agent | Secondary coding/research agent | https://github.com/google-gemini/gemini-cli |
| Continue CLI | cn |
Continue terminal agent | Optional coding-agent surface | https://docs.continue.dev/ |
| Goose | goose |
Block's coding agent | Optional agent execution | https://block.github.io/goose/ |
| Gollama | gollama |
Ollama-oriented terminal helper | Local-model convenience | Upstream project |
| ClaudeX | claudex |
Claude-oriented helper tooling | Optional agent surface | Installed package authority |
| Agent Browser | agent-browser |
Browser automation for agents | Automated web interaction where approved | Upstream package |
| Codegraph | codegraph |
Code relationship/graph utility | Repository understanding | Upstream package |
| Caveman AI | cave / caveman |
AI agent/development CLI | Experimental/optional agent tooling | Upstream package |
| OpenClaw | openclaw |
Agent gateway/runtime | Bluefly agent gateway | Project/upstream source |
| OSSA CLI | ossa |
Open Standard for Software Agents tooling | Standards/tooling work | Bluefly/OSSA source |
| Drupal Canvas CLI | canvas |
Drupal Canvas CLI | Canvas component/development workflows | Drupal project source |
Rule: an AI CLI is an execution surface. It does not become the durable scheduler, source authority, or secret authority. Durable work still belongs in the governed work graph and source changes still belong in GitLab.
8. MCP and Agent Integration¶
| Software | Base command | Purpose |
|---|---|---|
| MCP Filesystem Server | mcp-server-filesystem |
Controlled filesystem access over MCP |
| MCP GitLab Server | mcp-server-gitlab |
GitLab capabilities over MCP |
| MCP Memory Server | mcp-server-memory |
MCP memory/context service |
| MCP PostgreSQL Server | mcp-server-postgres |
PostgreSQL operations over MCP |
| MCP Redis Server | mcp-server-redis |
Redis operations over MCP |
| MCP Sequential Thinking | mcp-server-sequential-thinking |
Structured reasoning/planning service |
| MCP Zotero | mcp-zotero |
Zotero research-library integration |
For each MCP server, the server's package/project is the command authority. Bluefly defines whether and where it may be connected, not a competing CLI syntax.
9. Containers, Kubernetes, Cloud, and IaC¶
| Software | Base command | What it does | Bluefly use | Authority |
|---|---|---|---|---|
| Docker | docker |
Container runtime | Approved container inspection/build/runtime | https://docs.docker.com/reference/cli/docker/ |
| Docker Compose | docker compose |
Multi-container service composition | Local/service stacks | https://docs.docker.com/compose/ |
| Terraform | terraform |
Infrastructure as code | Existing Terraform estates | https://developer.hashicorp.com/terraform/cli |
| OpenTofu | tofu |
Open-source IaC engine | Selected Terraform-compatible estates | https://opentofu.org/docs/cli/ |
| Helm | helm |
Kubernetes package manager | Kubernetes applications | https://helm.sh/docs/ |
| Kustomize | kustomize |
Kubernetes manifest overlays | Declarative Kubernetes configuration | https://kubectl.docs.kubernetes.io/references/kustomize/ |
| K9s | k9s |
Interactive Kubernetes TUI | Human cluster inspection | https://k9scli.io/ |
| OCI CLI | oci |
Oracle Cloud API client | Oracle operations not already covered by IaC | https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm |
| Coder | coder |
Remote development workspaces | Optional remote dev execution | https://coder.com/docs |
| code-server | code-server |
Browser-hosted VS Code | Remote IDE surface | https://coder.com/docs/code-server |
| Cloudflared | cloudflared |
Cloudflare Tunnel | Governed ingress | https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/ |
| ngrok | ngrok |
Ad-hoc tunnels | Development/testing only unless specifically governed | https://ngrok.com/docs/ |
| Tailscale | tailscale |
Private mesh network | Private Oracle/NAS/operator connectivity | https://tailscale.com/docs/reference/tailscale-cli |
IaC discovery commands¶
terraform --help
terraform version
tofu --help
tofu version
oci --help
Do not make an SSH hotfix the desired state. Production infrastructure changes should converge through governed IaC.
10. Web, API, and Schema Tooling¶
| Software | Base command | What it does | Authority |
|---|---|---|---|
| Nginx | nginx |
Web server/reverse proxy | https://nginx.org/en/docs/ |
| Wrangler | wrangler |
Cloudflare Workers CLI | https://developers.cloudflare.com/workers/wrangler/ |
| Firecrawl CLI | firecrawl |
Crawl/extract web content | https://docs.firecrawl.dev/ |
| Dredd | dredd |
API contract testing | https://dredd.org/ |
| Spectral | spectral |
OpenAPI/JSON/YAML linting | https://docs.stoplight.io/docs/spectral/ |
| Redocly CLI | redocly / installed alias |
OpenAPI lint/bundle/docs | https://redocly.com/docs/cli |
| OpenAPI Generator | openapi-generator-cli |
Generate clients/servers/models | https://openapi-generator.tech/ |
| AJV CLI | ajv |
JSON Schema validation | https://ajv.js.org/ |
| Buf | buf |
Protobuf/schema build/lint/breaking checks | https://buf.build/docs/ |
11. Databases and Data Services¶
| Software | Base command | What it does | Bluefly use |
|---|---|---|---|
| Dolt | dolt |
Versioned SQL database | Beads/Gas City substrate where configured |
| ClickHouse | clickhouse |
Column-oriented analytics DB | Analytics/data workloads |
| Redis | redis-server / redis-cli |
In-memory KV/cache/queue | Application/runtime services |
| PostgreSQL tools | psql |
PostgreSQL client | DB operations where project-owned |
| pgcopydb | pgcopydb |
PostgreSQL migration/copy | Database migration |
| FreeTDS utilities | tsql, fisql, etc. |
SQL Server/Sybase connectivity | Specialized database interoperability |
Use the application/owning workflow before directly manipulating production databases.
12. Languages and Runtime Toolchains¶
| Software | Base command | Purpose |
|---|---|---|
| Node.js | node |
JavaScript runtime |
| npm | npm |
Node package manager |
| npx | npx |
Execute Node package binaries |
| pnpm | pnpm |
Efficient Node package manager |
| Yarn | yarn |
Node package manager |
| Bun | bun |
JS runtime/package manager/test/bundler |
| Deno | deno |
TypeScript/JavaScript runtime |
| Go | go |
Go compiler/toolchain |
| Python | python3 |
Python runtime |
| Python 3.13 | python3.13 |
Parallel Python runtime |
| Python 3.12 | python3.12 |
Parallel Python runtime |
| pyenv | pyenv |
Python version manager |
| uv | uv |
Python project/package/environment manager |
| pipx | pipx |
Isolated Python CLI installation |
| Ruby | ruby |
Ruby runtime |
| Bundler | bundle |
Ruby dependency manager |
| .NET | dotnet |
.NET SDK/runtime |
| Lua | lua |
Lua runtime |
| Bash | bash |
Shell runtime |
| Fish | fish |
Interactive shell |
Use repository-defined runtime constraints and lockfiles before selecting a globally installed version.
13. Code Quality, Testing, and Static Analysis¶
| Software | Base command | What it does |
|---|---|---|
| Lefthook | lefthook |
Git hooks and local quality gates |
| ShellCheck | shellcheck |
Shell script static analysis |
| Black | black |
Python formatter |
| mypy | mypy |
Python static typing |
| ast-grep | ast-grep |
Syntax-aware structural search and rewrite |
| Bats | bats |
Bash automated testing |
| Betterleaks | betterleaks |
Leak/diagnostic utility |
| compiledb | compiledb |
Compilation-database generation |
Repository CI remains the final delivery gate even when local checks pass.
14. Terminal and Developer Productivity¶
| Software | Base command | What it does |
|---|---|---|
| tmux | tmux |
Persistent/multiplexed terminal sessions |
| fzf | fzf |
Interactive fuzzy finder |
| fd | fd |
Fast filesystem search |
| bat | bat |
Syntax-highlighted file viewer |
| eza | eza |
Modern ls replacement |
| zoxide | zoxide |
Learned directory navigation |
| autojump | autojump |
Directory navigation helper |
| tree | tree |
Directory tree display |
| ncdu | ncdu |
Interactive disk usage |
| htop | htop |
Interactive process monitor |
| direnv | direnv |
Per-directory environment loading |
| mise | mise |
runtime/tool/environment manager |
| fswatch | fswatch |
Filesystem event watcher |
| mosh | mosh |
Resilient remote terminal |
| rclone | rclone |
Cloud/object-storage file synchronization |
| jq | jq |
JSON query/transformation |
| yq | yq |
YAML query/transformation |
| xq | xq |
XML query/transformation wrapper |
These tools improve operator efficiency but do not own application or platform state.
15. Networking and Diagnostics¶
| Software | Base command | What it does |
|---|---|---|
| Tailscale | tailscale |
Private mesh networking |
| Cloudflared | cloudflared |
Cloudflare Tunnel |
| Nmap | nmap |
Network/service discovery |
| socat | socat |
Socket/data relay |
| wget | wget |
HTTP/HTTPS retrieval |
| curl | curl |
HTTP/API client |
| mosh | mosh |
Resilient remote shell |
| ssh | ssh |
Secure remote shell |
| sshpass | sshpass |
Password injection into SSH; avoid in governed workflows |
| c-ares tools | adig, ahost |
DNS diagnostics |
For Bluefly production access, private Tailscale connectivity and governed SSH identity are preferred over public exposure.
16. Documentation, PDF, and Content Tooling¶
| Software | Base command | What it does |
|---|---|---|
| Pandoc | pandoc |
Document format conversion |
| MkDocs | mkdocs |
Markdown documentation sites |
| LibreOffice | soffice |
Office document conversion/automation |
| Tesseract | tesseract |
OCR |
| Poppler | pdfinfo, pdftotext |
PDF inspection/text extraction |
| yt-dlp | yt-dlp |
Video/audio retrieval and metadata |
| Docling | docling-view / package commands |
Document parsing/view tooling |
| Aspell | aspell |
Spell checking |
| gettext | gettext |
Localization/message tooling |
17. Media and Image Tooling¶
| Software | Base command | What it does |
|---|---|---|
| FFmpeg | ffmpeg |
Audio/video conversion and processing |
| FFprobe | ffprobe |
Media stream/metadata inspection |
| FFplay | ffplay |
Media playback |
| ImageMagick | magick |
Image conversion/manipulation |
| JPEG XL | cjxl, djxl |
JPEG XL encode/decode |
| WebP | cwebp, dwebp |
WebP encode/decode |
| AVIF | avifenc, avifdec |
AVIF encode/decode |
| x264 | x264 |
H.264 encoding |
| x265 | x265 |
H.265/HEVC encoding |
| Ghostscript | gs |
PostScript/PDF processing |
Many helper binaries in /opt/homebrew/bin belong to these packages. Do not treat every helper executable as a separate installed product.
18. Apple, Mobile, and Embedded Development¶
| Software | Base command | What it does |
|---|---|---|
| Fastlane | fastlane |
iOS/Android build, signing, release automation |
| XcodeGen | xcodegen |
Generate Xcode projects from declarative specs |
| libimobiledevice | afcclient and related tools |
iPhone/iPad communication |
| Arduino CLI | arduino-cli |
Arduino build/library/board management |
| PlatformIO | pio |
Embedded/IoT build and deployment |
19. Bluefly-Specific CLIs¶
| CLI | Owner | Purpose | Authority |
|---|---|---|---|
blu / blu-cli |
Bluefly | Operator facade and governed integration surface | Bluefly source repository |
qmd |
Bluefly/local knowledge index | Search/read indexed documentation before curation or implementation | Bluefly integration source |
agent-buildkit |
Bluefly | Repeatable engineering execution surface | Bluefly source repository |
| ContextControl CLI | Bluefly / ContextControl | Tenant/context/memory/receipt integration | ContextControl source/docs |
ossa |
Bluefly / OSSA | OSSA standards tooling | OSSA source/docs |
A Bluefly wrapper must not become a secret manager, duplicate an upstream tool, or conceal which upstream authority actually owns the operation.
20. Installed Command Aliases and Package Families¶
The original machine inventory is a listing of executable links, not a list of independent software products.
Examples:
| Commands seen | Product |
|---|---|
bd, beads |
Beads |
ffmpeg, ffprobe, ffplay, many codec/test helpers |
FFmpeg |
magick, convert, compare, composite, display |
ImageMagick |
cwebp, dwebp, gif2webp |
WebP tools |
cjxl, djxl, benchmark_xl |
JPEG XL |
git-lfs |
Git LFS |
gcat, gls, gcp, gmv, etc. |
GNU Coreutils installed with g prefix on macOS |
age, age-keygen, age-inspect |
age |
fish, fish_indent, fish_key_reader |
Fish shell |
fc-cache, fc-list, fc-match, etc. |
Fontconfig |
ddev, ddev-hostname |
DDEV |
bundle, bundler |
Ruby Bundler |
bun, bunx |
Bun |
op command family |
1Password CLI |
This distinction keeps the reference usable: learn the owning product, not every helper executable it installs.
21. Command Discovery Pattern¶
When you encounter an unfamiliar command:
command -v COMMAND
COMMAND --version
COMMAND --help
For Homebrew-managed software:
brew info PACKAGE
brew list PACKAGE
For a symlinked executable:
ls -l "$(command -v COMMAND)"
This identifies the package owner without guessing from the executable name.
22. Upstream Authority Map¶
| Area | Authority |
|---|---|
| Gas City overview and primitives | https://docs.gascity.com/getting-started/how-gas-city-works |
| Gas City CLI/config reference | https://docs.gascity.com/reference/ |
| Gas City configuration schema | https://docs.gascity.com/reference/config |
| Gas City CLI | https://docs.gascityhall.ai/usage/ |
| Beads CLI | https://beads.gascity.com/cli-reference |
| Dolt CLI | https://www.dolthub.com/docs/cli-reference/cli/ |
| Git | https://git-scm.com/docs |
| GitLab CLI | https://docs.gitlab.com/cli/ |
| Docker CLI | https://docs.docker.com/reference/cli/docker/ |
| Terraform CLI | https://developer.hashicorp.com/terraform/cli |
| OpenTofu CLI | https://opentofu.org/docs/cli/ |
| DDEV | https://docs.ddev.com/en/stable/users/usage/cli/ |
| Composer | https://getcomposer.org/doc/03-cli.md |
| Drush | https://www.drush.org/ |
| 1Password CLI | https://www.1password.dev/cli |
| Tailscale CLI | https://tailscale.com/docs/reference/tailscale-cli |
| Cloudflare Tunnel | https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/ |
| OCI CLI | https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm |
| OpenAI Codex CLI | https://developers.openai.com/codex/cli/ |
| Gemini CLI | https://github.com/google-gemini/gemini-cli |
23. What This Reference Must Not Become¶
This document may record:
- which software owns a category of work,
- the base executable,
- upstream authority,
- Bluefly-specific ownership and policy,
- safe discovery/help commands,
- the integration boundary,
- which tool is preferred over a lower-level alternative,
- runtime state that must remain uncommitted.
This document must not become:
- a copied upstream CLI manual,
- a second lifecycle specification for Gas City, Beads, GitLab, DDEV, or Terraform,
- a secret-handling cookbook,
- a collection of stale one-off incident commands,
- a reason to bypass an owning abstraction,
- a workstation-specific source of runtime truth,
- a dump of operator-home paths, live ports, MR numbers, or temporary
gc doctorfailures.
If behavior is unclear:
INSTALLED CLI HELP
-> CURRENT UPSTREAM DOCS
-> CURRENT SOURCE
-> AUTHORITATIVE RUNTIME EVIDENCE
-> RECORD THE GAP
Do not guess.
24. Quick Operator Card¶
WORK / FACTORY
gc Gas City
bd Beads
dolt Dolt
gt Gas City upstream
SOURCE / DELIVERY
git Git
glab GitLab
gitlab-runner GitLab CI runner
AUTH
op 1Password
DRUPAL
ddev Local environment
ddev drush Drupal runtime
composer PHP/Drupal dependencies
AGENTS
codex OpenAI coding agent
gemini Gemini coding agent
openclaw Agent gateway
INFRA
terraform Terraform
tofu OpenTofu
oci Oracle Cloud
docker Containers
helm Kubernetes packages
k9s Kubernetes TUI
NETWORK
tailscale Private mesh
cloudflared Cloudflare Tunnel
TERMINAL
tmux Persistent terminal sessions
fzf Fuzzy finder
fd File search
bat File viewer
eza Directory listing
jq JSON
yq YAML
25. Final Rule¶
Use the highest-level owning tool that correctly represents the operation.
Examples:
Durable work -> Beads / Gas City
Source/MR/CI -> Git + GitLab
Secrets -> 1Password
Drupal runtime -> DDEV + Drush
Drupal packages -> Composer
Infrastructure -> governed IaC
Private connectivity -> Tailscale
Ingress -> Cloudflare Tunnel where declared
Database internals -> Dolt only when the owning workflow requires it
The fact that a binary is installed does not make it an authority.