On this page

Authentication
guara login
guara logout
guara whoami
Context
guara link
guara unlink
guara open
Projects
guara projects create
guara projects list
guara projects info
Services
guara services create
guara services list
guara services info
guara services start
guara services stop
guara services restart
guara services delete
guara services auto-deploy
guara services resize
guara services backups
guara services restore
guara services credentials
Service Catalog
guara catalog list
guara catalog info <slug>
guara catalog deploy [slug]
Deployments
guara deploy
guara deployments list
guara rollback
Logs
guara logs
guara build-logs
Sessions
guara exec
guara proxy
Scaling
guara scale
Environment Variables
guara env set
guara env list
guara env unset
Domains
guara domains add
guara domains list
guara domains remove
Configuration
guara config get
guara config set
guara config list
guara config reset
Platform
guara status

CLI Commands

Complete reference for every guara command. All commands support --json, --quiet, and the global flags described in the overview.

Authentication

`guara login`

Authenticate with GuaraCloud.

guara login                          # Browser-based OAuth (default)
guara login --api-key gk_live_abc123 # Direct API key login
guara login --browser                # Force browser login

Flag	Description
`--api-key <key>`	Authenticate directly with an API key. Also reads `GUARA_API_KEY`.
`--browser`	Force browser-based OAuth login.

`guara logout`

Log out and remove stored credentials from the keychain and config file.

guara logout

`guara whoami`

Show the currently authenticated user.

guara whoami
guara whoami --json

Output includes name, email, tier, role, and founder status.

Context

`guara link`

Link the current directory to a GuaraCloud project and optionally a service. Creates a .guara.json file.

guara link                                              # Interactive picker
guara link --project my-project                         # Link to project only
guara link --project my-project --service my-api        # Link to project + service
guara link --yes                                        # Overwrite existing link without prompt

Flag	Short	Description
`--project <slug>`	`-p`	Project slug (skips interactive picker).
`--service <slug>`	`-s`	Service slug (skips interactive picker).

`guara unlink`

Remove the .guara.json link file from the current directory.

guara unlink

`guara open`

Open the project or service in the web dashboard (or the live URL).

guara open                                                  # Open dashboard
guara open --url                                            # Open the service's live URL
guara open --project my-project --service my-api --url      # Explicit target

Flag	Description
`--url`	Open the service live URL instead of the dashboard.

Projects

`guara projects create`

Create a new project.

guara projects create                                  # Interactive prompt
guara projects create --name my-project                # Non-interactive
guara projects create --name my-project --json         # JSON output

Flag	Short	Description
`--name <name>`	`-n`	Project name.
`--description <text>`	`-d`	Project description.
`--region <region>`	`-r`	Deploy region (default: `br-gru`).

`guara projects list`

List all projects in your account.

guara projects list
guara projects list --json

`guara projects info`

Show details of a project.

guara projects info --project my-project
guara projects info --json

Services

`guara services create`

Create a new service in a project.

guara services create                                                  # Interactive
guara services create --name my-api --build-method dockerfile --port 3000
guara services create --name my-api --build-method buildpack --repo https://github.com/user/repo --port 8080

Flag	Short	Description
`--name <name>`	`-n`	Service name.
`--build-method <method>`	`-b`	Build method: `dockerfile` or `buildpack`.
`--repo <url>`		GitHub repository URL.
`--branch <branch>`		Git branch (default: main).
`--port <number>`		Container port.
`--root-dir <path>`		Root directory for the build (default: `.`).
`--dockerfile-path <path>`		Custom Dockerfile path relative to root (default: `Dockerfile`).
`--build-cmd <command>`		Custom build command for buildpack monorepo builds.
`--start-cmd <command>`		Custom start command for buildpack monorepo builds.
`--public`		Make service publicly accessible.
`--service-type <type>`		Service type: `web` (default) or `worker`. Workers run in the background with no HTTP endpoint.
`--auto-deploy`		Enable automatic deploys on GitHub push (default: on). Use `--no-auto-deploy` to disable.

`guara services list`

List all services in a project.

guara services list --project my-project
guara services list --json

`guara services info`

Show details of a service including resources, autoscaling, and repository info.

guara services info --project my-project --service my-api
guara services info --json

`guara services start`

Start a stopped service.

guara services start --project my-project --service my-api

`guara services stop`

Stop a service (scale to zero).

guara services stop --project my-project --service my-api

`guara services restart`

Trigger a rolling restart of a service.

guara services restart --project my-project --service my-api

`guara services delete`

Delete a service. Requires confirmation.

guara services delete --project my-project --service my-api          # Interactive confirmation
guara services delete --project my-project --service my-api --yes    # Skip confirmation

`guara services auto-deploy`

Enable or disable automatic deploys on GitHub push.

guara services auto-deploy on --project my-project --service my-api
guara services auto-deploy off --project my-project --service my-api

Takes on or off as a positional argument. When enabled, pushes to the configured branch trigger a new deployment automatically.

`guara services resize`

Resize the persistent storage of a catalog service. Only works for catalog services with the persistent-storage capability.

guara services resize --project my-project --service my-db --size 5

Flag	Description
`--size <gi>`	New storage size in GiB (must be larger than current size).

Storage can only be expanded, never shrunk.

`guara services backups`

List backup snapshots for a catalog service. Only for services with the backup capability.

guara services backups --project my-project --service my-db
guara services backups --json

`guara services restore`

Restore a catalog service from a backup snapshot. Only for services with the backup capability.

guara services restore --project my-project --service my-db --snapshot snap-name
guara services restore --project my-project --service my-db --snapshot snap-name --async

Flag	Description
`--snapshot <name>`	Snapshot name to restore from (required).
`--async`	Do not wait for the service to reach `running` status.

`guara services credentials`

Show connection credentials for a catalog service.

guara services credentials --project my-project --service my-db
guara services credentials --json

Displays the connection string and individual fields (host, port, username, password).

Service Catalog

`guara catalog list`

List available managed services in the catalog (PostgreSQL, Redis, MongoDB, etc.).

guara catalog list
guara catalog list --json

Shows name, slug, category, supported versions, and capabilities for each service.

`guara catalog info <slug>`

Show details of a specific catalog service definition.

guara catalog info postgres
guara catalog info redis --json

Displays versions, storage options, and user-configurable options.

`guara catalog deploy [slug]`

Deploy a managed service from the catalog to your project.

guara catalog deploy                                          # Interactive picker
guara catalog deploy postgres                                 # Deploy PostgreSQL
guara catalog deploy redis --name my-cache --version 7.4-alpine
guara catalog deploy postgres --name my-db --storage 5 --config databaseName=myapp
guara catalog deploy postgres --async                         # Don't wait for running status

Flag	Description
`--name <name>`	Service name.
`--version <tag>`	Version tag (e.g., `17-alpine` for PostgreSQL).
`--storage <gi>`	Storage size in GiB (default: 1).
`--config key=value`	Service-specific config (repeatable, e.g., `--config databaseName=app`).
`--async`	Do not wait for the service to reach `running` status.

Deployments

`guara deploy`

Trigger a new deployment for a service.

guara deploy                           # Deploy the default branch
guara deploy --branch develop          # Deploy a specific branch
guara deploy --commit abc123f          # Deploy a specific commit
guara deploy --json                    # JSON output (polls until terminal state)
guara deploy --quiet                   # Print only the deployment ID

Flag	Short	Description
`--branch <name>`	`-b`	Git branch to deploy.
`--commit <sha>`	`-c`	Specific commit SHA to deploy.

In interactive mode, the CLI shows a live spinner that tracks the deployment through pending, building, deploying, and healthy stages with an elapsed timer.

`guara deployments list`

List deployment history for a service.

guara deployments list
guara deployments list --project my-project --service my-api
guara deployments list --json

`guara rollback`

Rollback to a previous deployment.

guara rollback                         # Interactive picker from healthy deployments
guara rollback --deployment <id>       # Rollback to a specific deployment ID
guara rollback --deployment <id> --json

Flag	Short	Description
`--deployment <id>`	`-d`	Deployment ID to rollback to.

Logs

`guara logs`

View service logs with filtering and real-time following.

guara logs                                                  # Last 100 lines
guara logs --follow                                         # Real-time tail
guara logs --lines 500 --level error                        # Last 500 error lines
guara logs --since 1h --search "connection refused"         # Search in the last hour
guara logs --since 2026-03-30T00:00:00Z --until 2026-03-30T12:00:00Z  # Time range

Flag	Short	Description
`--follow`	`-f`	Follow logs in real time (polls every 2.5s).
`--lines <n>`	`-n`	Number of log lines to fetch (default: 100).
`--since <time>`		Start time. Relative (`1h`, `30m`, `2d`, `90s`) or ISO8601.
`--until <time>`		End time (ISO8601).
`--search <text>`		Filter logs by search text.
`--level <level>`		Filter by log level: `trace`, `debug`, `info`, `warn`, `error`, `fatal`.

`guara build-logs`

View build logs for a deployment. Build logs show the container image build output (Dockerfile or buildpack builds).

guara build-logs                                             # Latest deployment with build logs
guara build-logs --deployment abc12345                       # Specific deployment
guara build-logs --follow                                    # Follow in real time (stops when build completes)
guara build-logs --lines 500 --search "npm error"            # Last 500 lines matching "npm error"
guara build-logs --since 1h                                  # Build logs from the last hour

Flag	Short	Description
`--deployment <id>`	`-d`	Deployment ID. Defaults to the latest `dockerfile` or `buildpack` deployment.
`--follow`	`-f`	Follow build logs in real time. Stops automatically when the deployment reaches a terminal state.
`--lines <n>`	`-n`	Number of log lines to fetch (default: 100).
`--since <time>`		Start time. Relative (`1h`, `30m`, `2d`, `90s`) or ISO8601.
`--until <time>`		End time (ISO8601).
`--search <text>`		Filter build logs by search text.

Sessions

`guara exec`

Execute a command or start an interactive shell in a running service container.

guara exec                                                   # Interactive shell (default: /bin/sh)
guara exec --shell /bin/bash                                 # Interactive shell with bash
guara exec -- ls -la /app                                    # Run a single command and exit
guara exec --project my-app --service web -- cat /etc/hostname

Flag	Description
`--shell <path>`	Shell to use for interactive sessions (default: `/bin/sh`).

When no arguments are passed after --, the CLI opens a fully interactive PTY session with terminal resize support. When arguments are provided, the command runs once and the CLI exits with the remote process exit code.

`guara proxy`

Forward a local port to a running service, allowing you to connect to private services from your machine.

guara proxy                                                  # Random local port
guara proxy --local-port 8080                                # Specific local port
guara proxy --project my-app --service db --local-port 5432  # Connect to a database
guara proxy --json                                           # JSON output with connection details

Flag	Description
`--local-port <port>`	Local port to listen on (1–65535). A random available port is used if not specified.

The CLI prints the connection info (e.g., Forwarding localhost:8080 → pod-name:3000) and stays alive until you press Ctrl+C. The remote port is derived automatically from the service configuration.

Scaling

`guara scale`

Enable or disable autoscaling for a service.

guara scale --autoscaling on
guara scale --autoscaling off --project my-project --service my-api
guara scale --autoscaling on --json

Flag	Description
`--autoscaling <on\|off>`	Enable or disable autoscaling (required).

When autoscaling is enabled, the CLI displays the maximum number of replicas. The CLI shows the before and after state.

Environment Variables

`guara env set`

Set environment variables. Triggers a rolling restart.

guara env set KEY=value                                        # Set a single variable
guara env set KEY1=value1 KEY2=value2                          # Set multiple
guara env set --from-file .env                                 # Load from a .env file
guara env set DATABASE_URL=postgres://... --project my-project --service my-api
guara env set NPM_TOKEN=abc123 --build                         # Set as a build-time variable

Flag	Short	Description
`--from-file <path>`		Read KEY=VALUE pairs from a `.env` file.
`--build`	`-b`	Mark the variable as available at build time (passed as a Docker `ARG`).

Variables are merged with existing ones. To overwrite a variable, set it again with the new value.

`guara env list`

List environment variables for a service. The output includes a Build column indicating which variables are available at build time.

guara env list --project my-project --service my-api
guara env list --json

`guara env unset`

Remove environment variables. Triggers a rolling restart.

guara env unset DATABASE_URL                                   # Remove one
guara env unset DATABASE_URL REDIS_URL                         # Remove multiple

Domains

`guara domains add`

Add a custom domain to a service.

guara domains add --domain api.myapp.com --project my-project --service my-api

Flag	Description
`--domain <name>`	Domain name to add (required).

The CLI prints the CNAME target you need to configure in your DNS provider.

`guara domains list`

List domains for a service.

guara domains list --project my-project --service my-api
guara domains list --json

`guara domains remove`

Remove a custom domain from a service. Requires confirmation.

guara domains remove --domain api.myapp.com --yes

Flag	Description
`--domain <name>`	Domain name to remove (required).

Configuration

`guara config get`

Get a CLI configuration value.

guara config get apiUrl

`guara config set`

Set a CLI configuration value.

guara config set apiUrl https://api.staging.guaracloud.com

`guara config list`

List all CLI configuration values.

guara config list
guara config list --json

`guara config reset`

Reset CLI configuration to defaults.

guara config reset

Platform

`guara status`

Show GuaraCloud platform status. No authentication required.

guara status
guara status --json

Shows the overall platform status, individual component health, and any active incidents.