CLI Reference

Orbit registers as a plugin for the astromeshctl CLI (the astromeshctl.plugins entry point), so installing astromesh-orbit next to astromesh-cli adds the orbit subcommand.

astromeshctl orbit <command> [options]

Note

plan, apply, destroy, status and upgrade need OpenTofu or Terraform. Orbit uses $TOFU_PATH if it points at a file, then tofu, then terraform from your PATH. Every command runs it with -lock=false.

Every command that reads a config exits with code 1 and orbit.yaml not found. Run 'astromeshctl orbit init' first. when the file is missing.

orbit init

Generate orbit.yaml with an interactive wizard.

astromeshctl orbit init [--provider <name>] [--preset <tier>]

Flags:

Flag	Type	Default	Description
--provider	string	gcp	Answers the wizard’s provider prompt. An unknown provider fails before the wizard starts.
--preset	string	—	starter or pro; answers the wizard’s preset prompt. Without it, the wizard asks.

Caution

init always runs the interactive wizard; there is no non-interactive mode today. For CI, commit an orbit.yaml written by hand (see Configuration).

Example:

astromeshctl orbit init

  🛰️  Astromesh Orbit — Cloud Deployment Setup

  Cloud provider [gcp] (gcp): gcp
  GCP Project ID: my-project-123
  Region [us-central1/us-east1/us-west1/europe-west1/europe-west4/asia-east1/asia-southeast1/southamerica-east1] (us-central1):
  Deployment name (my-astromesh):
  Environment [develop/staging/production] (develop): production

    starter (~$15/mo) — no HA, 1GB cache
    pro (~$80/mo) — HA, 4GB cache

  Preset [starter/pro] (starter):

  OK orbit.yaml written

  OK .orbit/ added to .gitignore

Note

Orbit before v0.4.3 offered dev, which the orbit.yaml schema rejects; if an older wizard wrote environment: dev, change it to develop.

Side effects:

• Writes orbit.yaml in the current directory
• Appends .orbit/ to .gitignore (creating it if missing)

---

orbit plan

Validate the GCP project, render the Terraform files, and run terraform plan.

astromeshctl orbit plan [--config <path>]

Flags:

Flag	Type	Default	Description
--config	path	orbit.yaml	Path to the Orbit configuration file.

Example:

astromeshctl orbit plan

  Orbit Deployment Plan

  Validating... OK
  OK State bucket exists: gs://my-project-123-astromesh-orbit-state

  Resources to create: …
  Resources to update: …
  Resources to destroy: …

The counts come from scanning the plan’s text and include attribute lines, so they run high. For the exact plan, run tofu plan in .orbit/generated/.

Failure example — API not enabled:

  Validating... FAILED

    OK Authenticated as you@example.com
    OK Project my-project-123 found
    FAIL sqladmin.googleapis.com not enabled
      -> gcloud services enable sqladmin.googleapis.com --project=my-project-123

Validation failures exit with code 1; Orbit prints the remediation command but does not enable anything for you.

Side effects:

• Creates/overwrites .orbit/generated/*.tf
• Runs terraform init in .orbit/generated/
• Creates the Terraform state bucket if it does not exist yet (and, when authenticating with a service-account key, the VPC peering Cloud SQL needs)
• Does not create any stack resources

---

orbit apply

Validate, render and run terraform apply for the full stack.

astromeshctl orbit apply [--config <path>] [--auto-approve]

Flags:

Flag	Type	Default	Description
--config	path	orbit.yaml	Path to the Orbit configuration file.
--auto-approve	bool	false	Skip the confirmation prompt (for CI).

Caution

apply asks for confirmation before creating billable resources, and aborts on anything but yes — so a non-interactive run needs --auto-approve. Before v0.4.4 it did not ask at all. Run orbit plan first to see what will change.

Example:

astromeshctl orbit apply --config orbit.prod.yaml

  Astromesh Orbit -- Deploying

  OK State bucket exists: gs://my-project-123-astromesh-orbit-state

  OK Deployment complete!

         Endpoints
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Service ┃ URL                                        ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ runtime │ https://astromesh-runtime-abc123.run.app   │
└─────────┴────────────────────────────────────────────┘

  Environment file: .orbit/orbit.env

Side effects:

• Creates or updates cloud resources (Cloud Run, Cloud SQL, Memorystore, etc.)
• Creates the Terraform state bucket if needed
• Writes .orbit/orbit.env with the Terraform outputs
• Idempotent — safe to re-run after a partial failure
• Validates again before applying; with a service-account key, also sets up private services access

---

orbit status

Show the runtime service’s status from the Terraform outputs.

astromeshctl orbit status [--config <path>]

Flags:

Flag	Type	Default	Description
--config	path	orbit.yaml	Path to the Orbit configuration file.

Example:

astromeshctl orbit status

                                 Deployment Status
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Resource          ┃ Type                 ┃ Status  ┃ URL                                        ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ astromesh-runtime │ cloud_run_v2_service │ running │ https://astromesh-runtime-abc123.run.app   │
└───────────────────┴──────────────────────┴─────────┴────────────────────────────────────────────┘

  State bucket: my-project-123-astromesh-orbit-state

The status is running when the runtime_url output exists and not_found otherwise; it does not query the service or any other resource. It reads the outputs from .orbit/generated/, so run it from the project where you applied.

Side effects:

• Reads Terraform outputs (read-only)

---

orbit destroy

Tear down all provisioned resources with terraform destroy.

astromeshctl orbit destroy [--config <path>] [--auto-approve]

Flags:

Flag	Type	Default	Description
--config	path	orbit.yaml	Path to the Orbit configuration file.
--auto-approve	bool	false	Skip the confirmation prompt.

Example:

astromeshctl orbit destroy

This will destroy ALL infrastructure. Continue? [y/N]: y

  Destroying infrastructure...

  OK All resources destroyed.

Caution

The state bucket (gs://{'{project}'}-astromesh-orbit-state) is intentionally NOT deleted. It contains the record of what was destroyed. Remove it manually after confirming: gsutil rm -r gs://{'{bucket_name}'}.

Side effects:

• Destroys all cloud resources managed by Orbit
• Does NOT delete the state bucket, orbit.yaml or .orbit/

---

orbit eject

Write standalone Terraform files with no Orbit dependency, to manage directly with the terraform CLI.

astromeshctl orbit eject [--output-dir <path>]

Flags:

Flag	Type	Default	Description
--output-dir	path	./orbit-terraform	Directory where standalone Terraform files are written.

eject always reads ./orbit.yaml; it has no --config flag.

Example:

astromeshctl orbit eject --output-dir ./my-terraform

  OK Terraform files exported to my-terraform/
  These are standalone -- no Orbit dependency.

  Next steps:
    cd ./my-terraform
    terraform plan
    terraform apply

Key details:

• One .tf file per Orbit template (backend.tf, main.tf, cloud_run.tf, cloud_sql.tf, memorystore.tf, secrets.tf, networking.tf, iam.tf, storage.tf, artifact_registry.tf, monitoring.tf, variables.tf, outputs.tf), each with a header comment
• terraform.tfvars with project_id, region and deployment_name
• backend.tf points to the existing state bucket — no state migration needed
• Ejecting is non-destructive — orbit apply still works after ejecting. If you change the ejected files and apply them directly, state diverges from what Orbit renders

Side effects:

• Writes files to the output directory
• Does NOT modify any cloud resources, .orbit/ or orbit.yaml

---

orbit logs

Read the runtime service’s logs (astromesh-runtime) from Cloud Logging.

astromeshctl orbit logs [--config <path>] [--limit <n>] [--since <duration>]

Flags:

Flag	Type	Default	Description
--config	path	orbit.yaml	Path to the Orbit configuration file (for the project ID).
--limit	int	50	Maximum number of log entries to fetch.
--since	string	1h	Freshness window, e.g. 10m, 1h, 2d.

Example:

astromeshctl orbit logs --limit 20 --since 30m

Prints a table of timestamp, severity and message. With no entries it prints No log entries in the last 30m.; if gcloud is not authenticated it exits with code 1 and suggests gcloud auth login.

Side effects:

• Read-only — queries Cloud Logging

---

orbit upgrade

Re-render the Terraform templates after an astromesh-orbit package update and show a diff against .orbit/generated/.

astromeshctl orbit upgrade [--config <path>] [--apply]

Flags:

Flag	Type	Default	Description
--config	path	orbit.yaml	Path to the Orbit configuration file.
--apply	bool	false	Write the re-rendered templates to .orbit/generated/ (templates the package dropped are removed). Without it, only the diff is shown.

Example:

astromeshctl orbit upgrade

--- current/monitoring.tf
+++ new/monitoring.tf
...

Re-run with --apply to write these changes.

When nothing changed it prints Up to date — generated templates match this package.

Side effects:

• Without --apply: read-only, prints a diff
• With --apply: overwrites .orbit/generated/*.tf (does not run terraform apply; run orbit plan next)