GuaraCloud Platform

GuaraCloud is a Platform-as-a-Service that deploys containerized applications from GitHub repositories. Billing is in BRL (Brazilian Real).

Core Concepts

User — Authenticated via GitHub or Google OAuth. Has one subscription tier (hobby, pro, business, enterprise) that governs limits across all projects.

Project — Organizational unit containing one or more services. Each project is isolated.

Service — A deployable container within a project. Has its own subdomain, env vars, scaling config, and deployment history. Subdomain format: {service}-{project}.guaracloud.com.

Deployment — A build-and-deploy cycle triggered by git push, manual trigger, rollback, or config change. Tracks build status, image tag, commit SHA, and errors.

Domain — Each service gets an automatic subdomain. Users can add custom domains via CNAME verification.

Project Members — Role-based access: owner, admin, member, viewer.

CLI Installation

npm install -g @guaracloud/cli

Binary names: guara or guaracloud (interchangeable).

Requires Node.js >= 20.

Authentication

# Browser-based OAuth (interactive)
guara login

# Direct API key (non-interactive / CI)
guara login --api-key <key>

# Verify
guara whoami

API keys are stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). Falls back to config file if keychain unavailable.

Environment variable override: Set GUARA_API_KEY to skip stored credentials.

Context Resolution

Commands that need a project/service resolve context in this order:

1. --project / --service flags
2. GUARA_PROJECT / GUARA_SERVICE environment variables
3. .guara.json file (walked upward from current directory)

Link a directory to a project:

guara link
# Creates .guara.json with { "project": "slug", "service": "slug" }

Global Flags

Command Index

For full flag reference, see references/commands.md.

Tier Information

For tier limits, pricing, and quotas, see guaracloud.com/docs. The CLI will return descriptive errors when a tier limit is reached.

Important Rules

• Always use the guara CLI. Do not call the REST API directly.
• Check service status before suggesting actions. Run guara services info to see current state.
• Use --json for scripting. Parse structured output instead of scraping human-readable text.
• Link projects with guara link so context resolution works automatically.