CLI reference
The commands you will use day to day, with examples.
This page covers the commands that carry the common workflows. For the complete surface see All commands; for flags on any command, guidal <group> <command> --help is always authoritative for the version you have installed.
Authentication
guidal login # sign in through the browser
guidal logout # sign out
guidal whoami # show the signed-in user
guidal auth status # show session state
guidal version # show the CLI versionOrganizations and projects
guidal orgs list
guidal orgs switch my-org
guidal projects list
guidal projects create --name my-app
guidal projects switch my-appswitch stores your working context so later commands do not need --org and --project. Both flags still work and override the stored value.
Build and deploy from source
guidal deploy . --service api # build on Guidal, roll out, wait
guidal deploy . --no-wait # build only; prints the build id
guidal builds list
guidal builds logs <build-id>
guidal builds cancel <build-id>See Deploy from source for what is uploaded and why secret files are refused.
Services
guidal services list
guidal services get api
guidal services create --name api --image ghcr.io/org/app:v1 --port 8080
guidal services deploy api --image ghcr.io/org/app:v2
guidal services scale api --replicas 3
guidal services delete apiCreate a background worker with --type worker and no port.
Deployments
guidal deployments list --service api
guidal deployments rollback --service api
guidal deployments diagnostics --service apidiagnostics is the first thing to run when a deploy fails and the reason is not obvious from logs.
Configuration
guidal env list --service api
guidal env set LOG_LEVEL=info --service api
guidal env delete LOG_LEVEL --service api
guidal env import .env.production --service api
guidal secrets list --service api
guidal secrets set STRIPE_API_KEY --service api
guidal secrets delete STRIPE_API_KEY --service apiSecret values are never printed back. Both take effect on the next deploy.
Databases and Redis
Both engines use the db group.
guidal db list
guidal db create --name demo-db --type postgresql
guidal db create --name cache --type redis
guidal db get demo-db
guidal db link demo-db --service api
guidal db unlink demo-db --service api
guidal db connect demo-db
guidal db proxy demo-db --port 0
guidal db credentials demo-db
guidal db delete demo-dbdb connect opens psql through a local tunnel without ever showing the password; db proxy opens the tunnel alone, for GUI tools. Both are PostgreSQL-only and need org admin or owner — see Postgres. Databases can be named by name or ID.
Backups and recovery:
guidal db backups demo-db
guidal db backup demo-db
guidal db restore demo-db --backup <backup-name> --as demo-db-restored
guidal db metrics demo-dbObject storage
guidal storage list
guidal storage create --name uploads
guidal storage ls uploads
guidal storage cp ./file.pdf uploads/file.pdf
guidal storage rm uploads/file.pdf
guidal storage presign uploads/file.pdf --expires 3600
guidal storage link uploads --service api
guidal storage delete uploadsDomains
guidal domains list
guidal domains add app.example.com --service api
guidal domains verify app.example.com
guidal domains ssl app.example.com
guidal domains remove app.example.comCron jobs
guidal cron list
guidal cron create --name nightly --slug nightly \
--image ghcr.io/org/app:v1 --command "python -m app.tasks.nightly" \
--schedule "0 2 * * *"
guidal cron trigger nightly
guidal cron suspend nightly
guidal cron resume nightly
guidal cron history nightly
guidal cron delete nightlyObservability
guidal logs query --service api
guidal logs deployment --service api
guidal metrics service api
guidal metrics tenantRegistry
guidal registry credentials # rotates: invalidates the previous credentials
guidal registry repos
guidal registry artifacts my-appMembers and access
guidal members list
guidal members invite someone@example.com --role developer
guidal members invites
guidal members role someone@example.com --role admin
guidal members remove someone@example.com
guidal api-keys list
guidal api-keys create ci-deploy
guidal api-keys delete ci-deployNetworking and billing
guidal network topology
guidal network endpoints
guidal billing status
guidal billing plan
guidal billing usage
guidal billing historyBilling commands are read-only. Changing a subscription is done in the dashboard.
MCP
guidal mcp setup
guidal mcp status
guidal mcp serve
guidal mcp remove