On this page

CLI Overview

The GuaraCloud CLI (guara) lets you deploy, manage, and monitor your services directly from the terminal. It is designed for both interactive use during development and non-interactive use in CI/CD pipelines.

Installation

Install the CLI globally with npm:

npm install -g @guaracloud/cli

After installing, verify it works:

guara --version

Quick start

Authenticate

Log in with your browser (opens an OAuth flow automatically):
```
guara login
```
Link your project

Navigate to your project directory and link it to a GuaraCloud project and service:
```
cd my-app
guara link
```
This creates a .guara.json file in the current directory so subsequent commands know which project and service to target.
Deploy

Trigger a deployment:
```
guara deploy
```
The CLI shows a live spinner with build progress and prints the live URL when the deployment is healthy.
View logs

Tail your service logs in real time:
```
guara logs --follow
```

What the CLI can do

The CLI covers the full lifecycle of your services on GuaraCloud:

Authentication — log in via browser OAuth or API key
Project management — create, list, and inspect projects
Service management — create, start, stop, restart, delete, and inspect services
Service catalog — browse and deploy managed databases, caches, and message queues
Deployments — trigger deploys, list deployment history, rollback to previous versions
Logs — query and follow service logs with filtering
Sessions — execute commands in containers (exec) and port-forward to private services (proxy)
Scaling — enable or disable autoscaling
Environment variables — set, list, and remove env vars (supports .env files)
Domains — add, list, and remove custom domains
Configuration — manage CLI settings like API URL

Global flags

Every command supports these flags:

Flag	Short	Description
`--json`		Output as JSON (ideal for scripting)
`--quiet`	`-q`	Suppress all non-essential output
`--project <slug>`	`-p`	Override the project (skips `.guara.json` lookup)
`--service <slug>`	`-s`	Override the service (skips `.guara.json` lookup)
`--api-key <key>`		Override the API key for this request
`--api-url <url>`		Override the API base URL
`--yes`	`-y`	Skip confirmation prompts

Output modes

The CLI supports three output modes to fit different workflows:

Interactive (default) — colored output with spinners, tables, and prompts
JSON (--json) — structured JSON output for piping into jq or other tools
Quiet (--quiet) — minimal output with only the essential value (ID, slug, or URL)

# Interactive mode (default)
guara services list

# JSON for scripting
guara services list --json | jq '.[].slug'

# Quiet for shell variables
SERVICE_ID=$(guara deploy --quiet)

Context resolution

The CLI resolves which project and service to operate on using this priority order:

Flags — --project and --service flags always take priority
Environment variables — GUARA_PROJECT and GUARA_SERVICE
Link file — .guara.json in the current directory (created by guara link)
Interactive prompt — if none of the above are set, the CLI prompts you to pick

Next steps

Authentication

Set up login, API keys, and CI/CD credentials.

Commands

Full reference for every CLI command and flag.

CI/CD

Integrate the CLI into GitHub Actions and GitLab CI.