Skip to content

cli.md

Latest commit

 

History

History
239 lines (189 loc) · 18.9 KB

cli.md

File metadata and controls

239 lines (189 loc) · 18.9 KB
Raw

dygo CLI

This document describes the dygo CLI command surface. Commands that are intentionally not part of the current surface are listed under Coming Soon.

Root

  • dygo - Shows the root help for the metadata-driven dygo platform CLI.
  • dygo new <name> - Creates a new dygo project skeleton.
  • dygo new <name> --module <path> - Sets the Go module path for the generated project.
  • dygo new <name> --skip-tidy - Skips go mod tidy after generating the project.
  • dygo upgrade - Upgrades the current project files, assets, and dependencies when the project dygo version differs from the installed dygo binary.
  • dygo upgrade --check - Checks whether the current project needs an upgrade without planning or writing changes.
  • dygo upgrade --to <version> - Plans or applies a project upgrade to the version embedded in the running dygo binary.
  • dygo upgrade --dry-run - Prints the project upgrade plan without writing or prompting.
  • dygo upgrade --yes - Applies the project upgrade without an interactive prompt.
  • dygo version - Prints the dygo version.
  • dygo completion <shell> - Generates shell completion scripts for bash, zsh, fish, or PowerShell.
  • dygo doctor - Diagnoses current project readiness.
  • dygo setup - Runs the first-run project setup flow, including Administrator bootstrap until the UI wizard owns it.
  • dygo dev - Runs the local development experience with backend, Studio dev server, proxying, and diagnostics.
  • dygo serve - Starts the dygo server.

dygo dev keeps the stable backend ready URL on stdout and writes local development diagnostics to stderr, including the project root, environment, Studio dev server startup, external Studio target when supplied, and Vite output. Loopback URLs are displayed as localhost, but dygo may still bind services to 127.0.0.1 for deterministic local-only networking. It must not print raw database URLs or decrypted secret values.

dygo doctor checks root/config, queue config, secrets, database connectivity, schema snapshot state, app, Entity, Job, and Schedule metadata, route conflicts, fixture validity, hook and Job runner wiring, generated project runner, Studio assets, and first-run setup state.

Database

  • dygo db - Groups database lifecycle commands.
  • dygo db check - Checks PostgreSQL connectivity for the configured environment.
  • dygo db create - Creates the configured PostgreSQL database.
  • dygo db drop - Prints the drop target, prompts interactively, then drops the configured PostgreSQL database.
  • dygo db drop --yes - Drops the configured PostgreSQL database without an interactive prompt.
  • dygo db migrate - Requires the configured database to exist, prints the migration plan, prompts, applies App state, patches, metadata, access, and Fixtures in one transaction, then refreshes the schema snapshot.
  • dygo db migrate --yes - Applies the migration workflow without an interactive prompt.
  • dygo db migrate --dry-run - Prints the migration plan without writing; if the database is missing, reports that it cannot plan without an existing database.
  • dygo db prepare - Creates the configured database if missing, then runs the same migration lifecycle.
  • dygo db prepare --yes - Prepares the database without an interactive prompt.
  • dygo db prepare --dry-run - Prints the prepare plan without writing.
  • dygo db prune - Prints the metadata-orphaned schema cleanup plan, prompts interactively, then removes approved objects.
  • dygo db prune --yes - Prints the cleanup plan and applies it without an interactive prompt.
  • dygo db prune --dry-run - Previews metadata-orphaned schema cleanup without writing.
  • dygo db reset - Destructively rebuilds a usable environment by printing the reset target, prompting interactively, then dropping, creating, and preparing the configured PostgreSQL database.
  • dygo db reset --yes - Drops, creates, and prepares the configured PostgreSQL database without an interactive prompt.
  • dygo db reset --dry-run - Prints the reset target and planned steps without writing.

Apps

  • dygo app - Groups dygo app commands.
  • dygo app list - Lists discovered apps, versions, labels, and install locations.
  • dygo app validate - Validates app manifests, app paths, dependencies, and reserved app metadata.
  • dygo app install <repository-url> - Clones an App repository, validates it with the current project, copies it to apps/<name> without Git metadata, and updates generated Hook and Job runner wiring. The repository root must contain app.yml. Run dygo db migrate separately to change a database.
  • dygo app install <repository-url> --dry-run - Clones and validates the App without writing project files.
  • dygo app install <repository-url> --yes - Installs the App and updates runner wiring without prompting.

Entities

  • dygo entity - Groups dygo Entity commands.
  • dygo entity list - Lists discovered normal, single, and collection Entities grouped by app.
  • dygo entity validate - Validates Entity metadata, collection metadata, route slugs, link targets, collection targets, field names, and hook file conventions.
  • dygo entity show <app>/<entity> - Prints resolved metadata for one Entity, including source path, kind, route slug, storage table, fields, links, collections, and naming.
  • dygo entity graph - Prints Entity link and collection relationships across discovered apps.
  • dygo entity graph <app> - Prints Entity relationships for one app.
  • dygo entity graph <app>/<entity> - Prints incoming and outgoing relationships for one Entity.

Fixtures

  • dygo fixture - Groups app-owned fixture Record commands.
  • dygo fixture validate - Validates fixture files, match fields, dependencies, and references without connecting to the database when possible.
  • dygo fixture export <app>/<entity> - Prints the fixture export plan, reports unresolved link dependencies, prompts interactively, then writes fixture files.
  • dygo fixture export <app>/<entity> --yes - Exports selected Records without an interactive prompt.
  • dygo fixture export <app>/<entity> --include-links - Exports selected Records and their linked fixture dependencies.
  • dygo fixture export <app>/<entity> --dry-run - Prints the fixture export plan without writing or prompting.

Hooks

  • dygo hook - Groups hook inspection and maintenance commands.
  • dygo hook list - Lists discovered hook packages, Entity hook files, runner wiring status, and compiled hook registrations when available.
  • dygo hook validate - Validates hook file conventions, Job Run files, generated registrars, and runner wiring.
  • dygo hook sync - Updates generated project runner wiring for discovered app hook and Job packages without creating hook or Job files.
  • dygo hook sync --dry-run - Prints runner wiring changes without writing.

Generate

dygo g is an alias for dygo generate.

  • dygo generate - Groups source scaffolding commands.
  • dygo generate app <app> - Generates a new app skeleton.
  • dygo generate app <app> --no-access - Skips access metadata skeleton creation.
  • dygo generate entity <app>/<entity> - Generates the standard Entity bundle.
  • dygo generate entity <app>/<entity> --no-access - Skips the Entity access file.
  • dygo generate collection <app>/<collection> - Generates reusable collection row Entity metadata.
  • dygo generate hook <app>/<entity> - Adds Entity hook scaffolding and project runner wiring to an existing Entity.
  • dygo generate job <app>/<job> - Adds Job metadata, a starter run.go, and project runner wiring.
  • dygo generate page <app>/<page> - Adds a Page bundle: YAML metadata, a Vue starter, and Page access.
  • dygo generate page <app>/<page> --no-access - Skips Page access metadata skeleton creation.
  • dygo generate fixture <app>/<entity> - Adds a fixture skeleton to an existing Entity.
  • dygo generate test <app>/<entity> - Adds Go test boilerplate for an existing Entity.

Generated files are valid boilerplate, not empty placeholders. Generators do not overwrite custom files. --force overwrites dygo-generated files only.

Collection generators create metadata only. Collection rows do not get fixture skeletons, route metadata, standalone permissions, or hooks by default; parent Entity fixtures and hooks own collection row usage. The intended collection file convention is entities/_collections/<collection>.yml.

dygo generate entity creates the Entity metadata and, unless skipped, its access and fixture skeletons. Use the narrower generate hook and generate test commands when you need hook wiring or Go test boilerplate.

  • dygo generate entity <app>/<entity> --dry-run - Prints files that would be created or updated without writing.
  • dygo generate entity <app>/<entity> --force - Overwrites dygo-generated files only; custom files still fail.
  • dygo generate entity <app>/<entity> --no-fixture - Skips fixture skeleton creation in the standard Entity bundle.
  • dygo generate app <app> --dry-run - Prints app skeleton files that would be created or updated without writing.
  • dygo generate app <app> --force - Overwrites dygo-generated app skeleton files only; custom files still fail.
  • dygo generate collection <app>/<collection> --dry-run - Prints collection metadata files that would be created or updated without writing.
  • dygo generate collection <app>/<collection> --force - Overwrites dygo-generated collection metadata only; custom files still fail.
  • dygo generate hook <app>/<entity> --dry-run - Prints hook scaffold and runner wiring changes without writing.
  • dygo generate hook <app>/<entity> --force - Refreshes generated runner wiring only; existing hooks.go files are developer-owned and are not overwritten.
  • dygo generate job <app>/<job> --dry-run - Prints Job scaffold and runner wiring changes without writing.
  • dygo generate job <app>/<job> --force - Refreshes dygo-generated Job metadata only; existing run.go files are developer-owned and are not overwritten.
  • dygo generate page <app>/<page> --dry-run - Prints Page files that would be created or updated without writing.
  • dygo generate page <app>/<page> --force - Overwrites dygo-generated Page YAML and access only; existing Vue files are not overwritten.
  • dygo generate fixture <app>/<entity> --dry-run - Prints fixture skeleton files that would be created or updated without writing.
  • dygo generate fixture <app>/<entity> --force - Overwrites dygo-generated fixture skeletons only; custom files still fail.
  • dygo generate test <app>/<entity> --dry-run - Prints Go test files that would be created or updated without writing.
  • dygo generate test <app>/<entity> --force - Overwrites dygo-generated Go test files only; custom files still fail.

Generators are non-interactive by default. They write when there are no conflicts, skip unchanged generated files, and fail on custom-file conflicts with a clear message.

Generator boilerplate lives as embedded templates under internal/generate/templates/. The dygo binary embeds these templates at build time instead of reading template files from disk at runtime.

Jobs

  • dygo job - Groups Job operations.
  • dygo job list - Lists registered Jobs from the selected environment database.
  • dygo job show <app>/<job> - Shows one registered Job's metadata and state.
  • dygo job disable <app>/<job> - Disables future enqueues for one Job without deleting metadata or history.
  • dygo job enable <app>/<job> - Re-enables future enqueues for one non-retired Job.
  • dygo job execution - Groups Job Execution operations.
  • dygo job exec - Short alias for dygo job execution.
  • dygo job execution run <app>/<job> - Queues one Job Execution for manual testing.
  • dygo job exec run <app>/<job> - Short alias for the same command.
  • dygo job execution run <app>/<job> --payload '{"example":true}' - Queues with a JSON payload; omitted payload defaults to {}.
  • dygo job execution run <app>/<job> --idempotency-key <key> - Queues with a stable duplicate-prevention key.
  • dygo job execution run <app>/<job> --env <environment> - Queues against development, staging, or production.
  • dygo job execution list - Lists recent Job Executions from the selected environment database.
  • dygo job execution list --limit 50 - Lists more recent executions; default limit is 20.
  • dygo job execution show <id-or-name> - Shows payload, result, error, timing, lock, retry, and idempotency details for one execution.
  • dygo job execution cancel <id-or-name> - Cancels one queued execution; running or finished executions are not cancelled.
  • dygo job execution retry <id-or-name> --idempotency-key <key> - Queues a fresh manual retry for one failed execution using the old payload and the new key.

Studio operators can cancel queued Job Executions and retry failed ones from Job Execution Records. system-manager needs Core Job access metadata applied.

job execution run enqueues durable work; it does not run the handler inline. Start dygo worker to process queued executions.

Routes

  • dygo route - Groups route registry inspection and validation commands.
  • dygo route list - Lists routeable Entities, Pages, effective slugs, owners, and reserved root slugs.
  • dygo route validate - Validates route slug conflicts, reserved root slugs, invalid slug syntax, and non-routeable collection usage.
  • dygo route resolve <path> - Explains which Studio, API, or Entity route would handle a path.
  • dygo route resolve <method> <path> - Explains which route, action, and permission a request would use.
  • dygo route reserved - Lists framework-reserved route slugs.

Access

  • dygo access - Groups app access metadata commands.
  • dygo access validate - Validates access/_roles.yml and access/<entity>.access.yml files.
  • dygo access list - Lists discovered Entity access files grouped by contributor app.
  • dygo access list <app> - Lists Entity access files contributed by one app.
  • dygo access show <app>/<entity> - Prints resolved access metadata for one Entity.
  • dygo access explain <app>/<entity> --user <email> --action <action> [--record <id>] - Reports roles, matching policies, row access, and denied fields without SQL.
  • dygo access roles - Lists app-owned roles grouped by app.
  • dygo access roles <app> - Lists app-owned roles for one app.
  • dygo access export --in <app> - Prints a role export plan, prompts interactively, then writes missing database roles into the selected app's _roles.yml.
  • dygo access export <app>/<entity> --in <app> - Prints an access export plan, prompts interactively, then writes one Entity access file and required role metadata under the selected destination app.
  • dygo access export <target> --yes - Exports access metadata without an interactive prompt.
  • dygo access export <target> --dry-run - Prints the access export plan without writing or prompting.

dygo access owns access validation, inspection, and export. dygo db migrate is the only command that applies access metadata to the database.

Secrets

  • dygo secret - Groups encrypted dygo secret commands.
  • dygo secret init - Initializes the root master key and encrypted environment secret files.
  • dygo secret get <name> - Prints one decrypted development secret value to stdout for scripts.
  • dygo secret get <name> --env <environment> - Prints one decrypted secret value for development, staging, or production.
  • dygo secret edit - Opens decrypted development secrets in an editor, then validates and re-encrypts them.
  • dygo secret edit --env <environment> - Opens decrypted secrets for development, staging, or production.
  • dygo secret validate - Validates development secrets and config references.
  • dygo secret validate --env <environment> - Validates encrypted secrets and config references for development, staging, or production.
  • dygo secret rotate-key - Prints the rotation plan, prompts interactively, then rotates .dygo/secrets/master.key and re-encrypts all environment secret files.
  • dygo secret rotate-key --yes - Rotates .dygo/secrets/master.key and re-encrypts all environment secret files without an interactive prompt.

Secret names support root keys and dot-separated YAML paths, such as DATABASE_URL or database.url. dygo secret get prints only the raw value to stdout; errors and diagnostics go to stderr.

Worker

  • dygo worker - Runs Job workers and checks due Schedules for all registered queues.
  • dygo worker --queue <queue> - Runs workers for one registered queue; the flag may be repeated.
  • dygo worker --once - Checks due Schedules, processes one available batch, and exits.
  • dygo worker --concurrency <n> - Overrides configured queue concurrency for this worker process.
  • dygo worker --poll-only - Disables PostgreSQL notifications and only polls for queued executions.
  • dygo worker --poll-interval <duration> - Sets the fallback polling interval; defaults to 60s.

Production deployments that use Jobs or Schedules should run dygo serve and dygo worker as separate long-running processes. dygo serve does not process queued Job Executions or due Schedules.

Coming Soon

  • Global --json - Coming after dygo has a consistent output contract for command results, validation errors, dry-run plans, prompts, redaction, and streaming commands.
  • Smart shell completions - Coming after the command structure is more stable; the first version should cover --env, <app>, <app>/<entity>, hook events, and completion shells.

Out Of Band Binary Updates

  • curl -fsSL https://dygo.dev/install | sh - Installs or updates the dygo binary outside the workspace CLI.
  • brew upgrade dygo - Future package-manager-owned binary update path.
  • go install github.com/hapyco/dygo/cmd/dygo@latest - Future Go toolchain-owned binary update path if dygo supports it.

Normal update flow:

curl -fsSL https://dygo.dev/install | sh
dygo upgrade

Environment Safety Rule

  • --env defaults to development.
  • Runtime and database write commands print the plan and prompt interactively by default when the action benefits from review.
  • --yes skips runtime write prompts for agents, scripts, and CI.
  • --dry-run prints the same runtime write plan and exits without writing or prompting.
  • Generator and scaffold writes are non-interactive by default: they write when there are no conflicts, support --dry-run for previews, support --force for dygo-generated files only, and fail on custom-file conflicts.
  • Destructive commands can run in development.
  • Protected environments such as staging and production block destructive commands unless --force is passed.
  • Read-only commands such as --dry-run, check, and validation commands never need --force.

Record encryption keys

  • dygo secret record-key init --env <environment> --yes: initialize the Record key in encrypted credentials without replacing an existing key.
  • dygo secret record-key rotate --env <environment> --offline --yes: re-encrypt Record secrets while servers and workers are stopped.
  • Add --dry-run to show the selected target without changes.

See Record encryption keys for backup and recovery steps.