CLI Reference

The Ghayma CLI (ghayma) lets you deploy and manage your applications, databases, storage, and auth apps from the terminal.

Installation

macOS / Linux

curl -fsSL https://dash.ghayma.cloud/install.sh | sh

Windows (PowerShell)

irm https://dash.ghayma.cloud/install.ps1 | iex

Check the installed version:

ghayma version

Authentication

ghayma register

Create a new Ghayma account from the terminal. You’ll be prompted for API host (defaults to https://api.ghayma.tech), full name, email, and a password (minimum 8 characters). On success, the CLI is automatically logged in and creates the long-lived CLI token described under ghayma login; if your account requires email verification, finish that first and then run ghayma login.

ghayma register

ghayma login

# Login via browser (default — opens dash.ghayma.cloud)
ghayma login
 
# Login with email/password prompts instead
ghayma login --email

The browser flow polls a one-time CLI session code until you confirm in the dashboard. Either way, the CLI then creates a long-lived API token for this machine and saves it to ~/.paas-cli.json:

🔑 Created a long-lived CLI token "ghayma-cli@my-laptop" (expires 2027-08-16). Revoke it with 'ghayma logout' or in the Dashboard → Settings → API Tokens.

The token is named ghayma-cli@<hostname>, has full scope, and expires after 365 days. It’s what the CLI sends on every request from then on, so you no longer get signed out after a week.

One token per machine. Logging in again on the same machine revokes that machine’s old token and creates a fresh one with the same name. Every token — name, prefix, scope, expiry, last used — is listed in the dashboard under Settings → API Tokens, where you can rotate it, revoke it, or read what it did on its Activity panel. Revoking is soft: the token stops working at once and its history stays. See Account Tokens.

If the token can’t be created — for example your account already holds the maximum of 10 live API tokens (revoked ones don’t count), or the call fails — login still succeeds and the CLI falls back to the 7-day session:

⚠️  Could not create a long-lived CLI token (<reason>) — using a 7-day session instead.

ghayma whoami

Show the current CLI identity — email, user ID, API endpoint, CLI version, and an Auth: line saying how the CLI is authenticating. Aliased as ghayma account.

ghayma whoami
ghayma account        # alias
 
# Machine-readable
ghayma whoami --json

Auth: reads long-lived CLI token, or 7-day session (expires …) when you’re on the session fallback — 7-day session (EXPIRED — run: ghayma login) once that session is past its expiry. With --json the same information comes back as auth_method ("api_token" or "session") plus session_expires_at (RFC3339, sessions only).

Tokens are never printed, even in --json output. When you’re not signed in, whoami prints ✗ Not signed in. Run: ghayma login and exits 1.

ghayma logout

ghayma logout

Revokes this machine’s CLI token on the server — best-effort, printing 🔒 Revoked the CLI token. — then removes ~/.paas-cli.json. If you weren’t logged in to begin with, prints ℹ️ Not logged in. and does nothing.

Expired sessions

If the CLI is still using a 7-day session (an older login, or the fallback above), every API command fails fast with a clear message instead of a network call:

❌ Your CLI session has expired (sessions last 7 days). Run: ghayma login

And if the server rejects the stored credential mid-flight, commands report session expired or revoked — run: ghayma login rather than quietly showing an empty list. ghayma link checks your session and lists your projects before asking the monorepo “App subdirectory” question, so a dead session can’t be mistaken for an empty account. Run ghayma login to get a long-lived token.

Global flags

There’s no -v shorthand. The installed CLI version is shown by ghayma version.

Deprecated command aliases

A few verbs were renamed in v0.2.8 to a consistent create / delete grammar: site add → site create, domain add → domain create, domain remove → domain delete, env remove → env delete. The old names still work as hidden deprecated aliases and print a one-line deprecation warning (throttled to once per week per shell); they are scheduled for removal in a future release. Update any scripts to the canonical names — they are what the rest of this CLI reference documents.

Commands

Project setup

ghayma status prints one line per project (name · framework · slug), or No projects yet. Run 'ghayma init' to create one. when your account is empty.

Deploy & runtime

Resources

Account