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]
guara catalog query
guara catalog schema
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
Observability commands
guara services metrics
guara services traces list
guara services traces get <traceId>
guara projects map
guara projects observatory
Cron Workers
guara crons list
guara crons info <slug>
guara crons create -f <file>
guara crons update <slug> -f <file>
guara crons delete <slug>
guara crons suspend <slug>
guara crons resume <slug>
guara crons trigger <slug>
guara crons runs <slug>
Profiling
guara services profiles get

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.

`guara catalog query`

Run a single, read-only SQL statement against a managed PostgreSQL or MySQL catalog service. Pass the SQL inline, from a file, or via stdin.

guara catalog query --query "SELECT id, email FROM users LIMIT 10"
guara catalog query --file ./reports/active.sql --format csv > active.csv
cat ./reports/active.sql | guara catalog query --service my-postgres
guara catalog query --query "SELECT count(*) FROM users" --quiet     # prints the row count

Flag	Short	Description
`--query <sql>`		Inline SQL statement (mutually exclusive with `--file`).
`--file <path>`	`-f`	Read SQL from a file (use `-` to read from stdin).
stdin (auto)		When neither flag is set and stdin is non-TTY, the SQL is read from the pipe.
`--format <table\|csv\|tsv>`		Output format when stdout is a TTY (default: `table`).
`--no-csv-safe`		Disable spreadsheet formula-injection neutralisation in CSV/TSV cells.

The platform enforces a 30 s statement timeout, a 50 KB query length cap, a 1 000 row response cap (truncated: true when exceeded), and at most 3 concurrent queries per user × service. See SQL Query for the full safety model and error codes.

`guara catalog schema`

Inspect the live schema of a managed PostgreSQL or MySQL catalog service.

guara catalog schema
guara catalog schema --filter users          # case-insensitive substring filter
guara catalog schema --json | jq .
guara catalog schema --quiet                 # one table name per line

Flag	Description
`--filter <substr>`	Only include tables whose name contains the substring.

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`, `unknown`.

`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.

Observability commands

GuaraCloud’s observability surfaces let you watch live resource usage and inspect distributed traces directly from the terminal. These commands are tier-aware: the API will clamp time windows, retention, and span counts to your subscription limits, and the CLI surfaces the visible window the server actually returned.

`guara services metrics`

View current resource usage (CPU, memory, network, pods, storage, bandwidth) for a service. Pass --watch to refresh in place every --interval seconds (default 5, minimum 2).

guara services metrics
guara services metrics --metric cpu --watch
guara services metrics --history 6h --json | jq .

Flag	Description
`-m, --metric <name>`	Focus a single metric. One of `cpu`, `memory`, `network`, `requests`, `response-time`, `storage`.
`-w, --watch`	Refresh in place every `--interval` seconds.
`-i, --interval <seconds>`	Poll interval in seconds (default `5`, minimum `2`).
`--history <window>`	Sparkline window. One of `15m`, `30m`, `1h`, `6h` (default `1h`).
`--no-history`	Skip the sparkline panel and only fetch the current snapshot.
`--no-pods`	Skip the pod table.

Sparklines render the last --history window. Tier-clamped — the response includes the actual visible window when your tier limits it. --json emits one NDJSON object per tick, suitable for piping into jq or a sidecar collector. In --quiet mode the command prints just the current CPU value in millicores so it can be wired into shell pipelines.

`guara services traces list`

List recent OpenTelemetry traces for a service. Filters narrow by latency, status, operation name, peer service, or HTTP status class.

guara services traces list
guara services traces list --status error --min-duration-ms 500
guara services traces list --quiet | xargs -I{} guara services traces get {}

Flag	Description
`-t, --time-range <window>`	Lookback window. One of `15m`, `30m`, `1h`, `6h`, `24h`, `7d` (default `15m`).
`-n, --limit <n>`	Max rows (1-100, default `20`).
`--status <state>`	Status filter. One of `ok`, `error`, `all` (default `all`).
`--operation <substring>`	Operation substring match.
`--service-name <name>`	Filter by `service.name` of any participating span.
`--min-duration-ms <ms>`	Latency floor.
`--max-duration-ms <ms>`	Latency ceiling.
`--http-status-class <class>`	HTTP status class. One of `2xx`, `4xx`, `5xx`.
`-w, --watch`	Stream new traces.
`-i, --interval <seconds>`	Poll interval in seconds (default `5`, minimum `2`).
`--ascii`	Use ASCII glyphs only (no Unicode). Also enabled by `NO_UNICODE=1`.

--watch polls the trace endpoint at --interval cadence. --quiet emits one trace_id per line so the output composes directly into xargs guara services traces get.

`guara services traces get <traceId>`

Render a single trace as an ASCII waterfall. Each row shows service · operation · positioned bar · duration · status. Traces are immutable, so this command never accepts --watch.

guara services traces get 4f2ab91d
guara services traces get 4f2ab91d --errors --depth 3
guara services traces get 4f2ab91d --json | jq .

Flag	Description
`--depth <n>`	Limit the nested span depth shown.
`--errors`	Highlight error spans only; non-errors are dimmed.
`--width <cols>`	Override the waterfall width (defaults to terminal columns).

Use --json to emit the raw TraceDetailResponse for downstream tooling. In --quiet mode the command prints one service::operation duration_ms status line per span.

`guara projects map`

Render the project’s service topology in the terminal — every service as a row in a nodes table and every inter-service edge in an edges table. Aliased as guara projects topology.

guara projects map
guara projects map --graph
guara projects map --watch --interval 15 --time-range 1h

Flag	Description
`-t, --time-range <range>`	Lookback window. One of `15m`, `30m`, `1h`, `6h`, `24h`, `7d`. Defaults to `15m`.
`-g, --graph`	Render a best-effort layered ASCII graph instead of the edges table.
`--service <id>`	Highlight one service (by UUID) when rendering the graph.
`-w, --watch`	Refresh in place every `--interval` seconds.
`-i, --interval <seconds>`	Poll interval in seconds (default `15`, minimum `5`).

The default rendering is a nodes table plus an edges table because that fits any terminal width and keeps latency and error stats readable. --graph switches to a layered ASCII diagram and falls back to the edges table automatically when the layout would exceed the terminal width.

Edges show the same paired (HTTP, via Tempo service-graphs) versus l4_flow (TCP, via Beyla kernel flows) distinction the dashboard uses — paired edges carry full latency percentiles and error rate, while l4_flow edges show a dashed cell for those columns plus a byte-rate suffix on the request column. See Topology and Observatory for the underlying model.

--quiet prints one source_slug -> target_slug line per edge, which composes well with awk, comm, or xargs in scripts.

`guara projects observatory`

Render a live mission-control view of the project: aggregate health bar, scrolling event feed and live trace timeline. Aliased as guara projects obs. Watch is on by default; use --no-watch for a single snapshot.

guara projects observatory
guara projects observatory --no-watch --json
guara projects observatory --interval 10 --traces 30

Flag	Description
`--no-watch`	Print one snapshot and exit (use in scripts and CI checks).
`-i, --interval <seconds>`	Poll interval in seconds (default `5`, minimum `2`).
`--traces <n>`	Number of trace rows in the live trace panel (default `10`, max `30`).
`--events <n>`	Number of event rows in the event feed panel (default `15`, max `60`).
`--no-health`	Hide the project health bar.
`--no-events`	Hide the event feed panel.
`--no-traces`	Hide the live trace panel.

Each frame contains the project header, the one-line health bar (services healthy · req/min · err · avg latency · p99), the event feed (errors, deploys, alerts with relative timestamps) and the live trace timeline (newest first, with ok/err status and per-trace duration). --no-watch --json emits a single NDJSON snapshot and exits — combine with jq for scripted readiness checks. --quiet --no-watch prints just the health bar line so the output composes into shell pipelines.

Cron Workers

The crons topic manages cron workers — scheduled triggers that fire HTTP requests, publish to queues, or notify databases on a cron expression. All commands are project-scoped and accept the same --project / --json / --quiet global flags as every other command.

`guara crons list`

List cron workers in a project.

guara crons list
guara crons list --status active
guara crons list --watch --interval 10
guara crons list --json | jq .

Flag	Short	Description
`--status <state>`		Filter by status. One of `active`, `suspended`.
`-w, --watch`	`-w`	Repeatedly poll and re-render until interrupted.
`-i, --interval <seconds>`	`-i`	Poll interval in seconds (default `5`, minimum `2`).
`--ascii`		Use ASCII glyphs only (no Unicode). Also enabled by `NO_UNICODE=1`.

Sample output:

 SLUG          STATUS     SCHEDULE        TZ                  LAST RUN
 hourly        active     0 * * * *       UTC                 ●
 nightly       active     0 3 * * *       America/Sao_Paulo   ●
 cleanup       suspended  */15 * * * *    UTC                 ✕

The LAST RUN column is a single status dot — green ● for the last successful run, red ✕ for the last failed one, yellow ◐ while still running. With --watch, the table is redrawn in place each tick. With --watch --json, each tick emits one NDJSON line for piping into jq.

`guara crons info <slug>`

Show details of a cron worker, including resolved destination and payload template.

guara crons info hourly
guara crons info hourly --json

Flag	Description
`--ascii`	Use ASCII glyphs only (no Unicode). Also enabled by `NO_UNICODE=1`.

Sample output (TTY card view):

┌─ hourly ───────────────────────────────────  active ─┐
│ Name         Hourly cleanup job                      │
│ Schedule     0 * * * *  ·  UTC                       │
│ Destination  POST /jobs/cleanup-stale-uploads        │
│              Authorization: ***                      │
│              X-Job-Source: cron                      │
│ Timeout      30s  ·  Max retries 3                   │
│ Payload      {                                       │
│                "job": "rotate-uploads",              │
│                "max_age_hours": 24                   │
│              }                                       │
└──────────────────────────────────────────────────────┘

Sensitive HTTP headers (Authorization, Cookie, X-API-Key, X-Auth-Token) are redacted to ***. Use --json to get the raw CronWorkerResponse for downstream tooling.

`guara crons create -f <file>`

Create a cron worker from a YAML or JSON spec file.

guara crons create -f cron.yaml
guara crons create -f cron.json --json
guara crons create -f cron.yaml --project my-project

Flag	Short	Description
`-f, --file`	`-f`	Path to spec file (YAML by default, JSON detected by the `.json` extension).

The spec file mirrors the API request body — see Creating a Cron Worker → From the CLI for one full example per destination_type. Validation errors (HTTP 400 with field-level Zod issues) are pretty-printed with the offending key bolded and a hint where applicable.

`guara crons update <slug> -f <file>`

Update a cron worker from a YAML or JSON spec file. The destination type cannot be changed — you can only edit the configuration of the existing type.

guara crons update hourly -f cron.yaml
guara crons update hourly -f patch.json --json

Flag	Short	Description
`-f, --file`	`-f`	Path to spec file (YAML by default, JSON detected by the `.json` extension).

`guara crons delete <slug>`

Delete a cron worker. Run history is also deleted. Requires confirmation.

guara crons delete hourly                # Interactive confirmation
guara crons delete hourly --yes          # Skip confirmation
guara crons delete hourly --json --yes   # Script-friendly

Flag	Description
`--yes`	Skip the confirmation prompt. Required when using `--json` or `--quiet`.

`guara crons suspend <slug>`

Suspend a cron worker so its schedule stops firing. The worker keeps its full configuration and history; runs already in flight finish normally.

guara crons suspend hourly
guara crons suspend hourly --json

`guara crons resume <slug>`

Resume a suspended cron worker. Schedule restarts at the next slot — runs missed while suspended are not replayed.

guara crons resume hourly
guara crons resume hourly --json

`guara crons trigger <slug>`

Manually fire a cron worker. The run is enqueued asynchronously — the command returns as soon as the API accepts the trigger, not when the run finishes.

guara crons trigger hourly
guara crons trigger hourly --json

Sample output:

✓ Triggered hourly
  Inspect with: guara crons runs hourly --watch

The trigger goes through the same retry, timeout, and audit pipeline as scheduled runs and is rate-limited per worker. Use guara crons runs <slug> --watch to watch the resulting run land in history.

`guara crons runs <slug>`

List recent runs of a cron worker. By default renders a table; pass --detail for bordered cards (one card per run) including the failure reason explanation, error preview, and resolved payload.

guara crons runs hourly
guara crons runs hourly --detail
guara crons runs hourly --status failed --watch
guara crons runs hourly --limit 50 --cursor eyJ...

Flag	Short	Description
`-n, --limit <n>`	`-n`	Max rows per page (1-100, default `20`).
`--cursor <token>`		Pagination cursor (opaque, returned by the previous page).
`--status <state>`		Filter by run status. One of `running`, `success`, `failed`.
`--detail`		Render each run as a bordered card instead of a table.
`-w, --watch`	`-w`	Repeatedly poll page 1, deduping previously seen runs.
`-i, --interval <seconds>`	`-i`	Poll interval in seconds (default `5`, minimum `2`).
`--ascii`		Use ASCII glyphs only (no Unicode). Also enabled by `NO_UNICODE=1`.

Sample table output:

 ID         STATUS       STARTED                    DURATION   REASON
 4f2ab91d   ● success    2026-05-02T15:00:01.120Z   842ms      —
 3a18cc02   ● success    2026-05-02T14:00:00.943Z   915ms      —
 2c9f8de4   ✕ failed     2026-05-02T13:00:01.214Z   30001ms    timeout
 1bd47a8e   ● success    2026-05-02T12:00:00.812Z   771ms      —

With --watch, page 1 is polled every --interval seconds. In --detail mode, watched runs are deduped against a bounded recall set so the same run is never rendered twice. With --watch --json, each tick emits one NDJSON page.

Profiling

`guara services profiles get`

Render a CPU flamegraph for a service from the platform’s continuous profiling pipeline. See Continuous CPU Profiling for the underlying model.

guara services profiles get
guara services profiles get --time-range 1h --top 20
guara services profiles get --from 2026-05-02T15:00:00Z --to 2026-05-02T15:15:00Z
guara services profiles get --json | jq .data.metadata

Flag	Description
`--time-range <window>`	Preset window. One of `15m`, `30m`, `1h`, `6h`, `24h`, `7d` (default `15m`). Mutually exclusive with `--from`/`--to`.
`--from <iso>`	Start of explicit window (ISO-8601). Must be paired with `--to`.
`--to <iso>`	End of explicit window (ISO-8601). Must be paired with `--from`.
`--top <n>`	Number of frames in the top-N self-time table (default `10`).
`--width <cols>`	Override flamegraph width in columns (auto-detected from terminal when omitted, minimum 40).
`--ascii`	Use plain ASCII glyphs (compatible with non-Unicode terminals).

Sample output (truncated):

my-api · profile · 2026-05-02T15:00:00Z → 2026-05-02T15:15:00Z

▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇  100.0%  total
 ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇                         62.4%   handleRequest
  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇                                        38.1%   db.query
   ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇                                               25.8%   pg.client.send
  ▇▇▇▇▇▇▇▇                                                         12.6%   serialize
 ▇▇▇▇▇▇▇▇▇▇▇▇                                                      18.7%   gc.minorMark

Top 10 by self time
   #  SELF %   FRAME
   1   25.8%   pg.client.send
   2   18.7%   gc.minorMark
   3   12.6%   serialize
   4    8.4%   crypto.randomFillSync
   5    7.1%   net.write
   …

Tier: Pro · retention 168h · window 15m

When stdout is not a TTY (piped into another command, redirected to a file), the flamegraph itself is omitted and only the top-N table is printed for legibility. Use --json to get the raw ProfileResponse envelope ({ data: { flamebearer, metadata, … } }) for downstream tooling.