---
title: "CLI"
description: "Manage EZGH Cloud from the command line with ezgh."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

`ezgh` is the EZGH Cloud command-line tool. It manages organizations and projects, IAM, service quotas, Trails and OCR through the same public APIs as the console, with your IAM access. People log in with their EZGH Cloud account; code and CI use an [API key](/iam/api-keys).

- [Install the CLI](/cli/install): the installer for macOS, Linux and Windows, or a release archive.
- [Authentication](/cli/authentication): log in, use an API key, log out.
- [Profiles and configuration](/cli/profiles): separate logins and default settings, the configuration file, environment variables.
- [Command reference](/cli/reference): every command and flag.

```sh
curl -fsSL https://get.ezghcloud.com | sh
ezgh login
ezgh projects list
ezgh trails events --from 2h --event-name DeleteProject
```

## Commands

| Command | What it does |
| --- | --- |
| [`ezgh login`](/cli/reference/login), [`logout`](/cli/reference/logout), [`whoami`](/cli/reference/whoami), [`auth`](/cli/reference/auth) | Log in and out, and show who you are and which credential commands use |
| [`ezgh profiles`](/cli/reference/profiles), [`config`](/cli/reference/config) | Keep separate logins and default settings |
| [`ezgh orgs`](/cli/reference/orgs), [`projects`](/cli/reference/projects) | Show your organization, leave it, and manage projects |
| [`ezgh invitations`](/cli/reference/invitations) | See, accept and decline your own invitations into organizations |
| [`ezgh iam`](/cli/reference/iam) | Users, invitations, bots, groups, policies, API keys, SCIM, IAM actions, permission checks |
| [`ezgh quotas`](/cli/reference/quotas) | Service quotas, with their values and usage |
| [`ezgh trails`](/cli/reference/trails) | Look up Trails events, and run SQL queries over them |
| [`ezgh ocr`](/cli/reference/ocr) | OCR models and processors, and processing documents |
| [`ezgh completion`](/cli/reference/completion) | Shell completion for bash, zsh, fish and PowerShell |
| [`ezgh version`](/cli/reference/version) | The version, commit and build date |

`ezgh <command> --help` prints a command's help.

## Naming resources

Commands take an organization by ID or slug (`org_k3f9a0x2m7qp`); projects, bots, groups, policies and OCR processors by ID, slug or name; and users by ID or email. A name must match exactly one resource, or the command fails. Commands use your organization unless you choose another with `--org`; commands that work in a project take `--project`. See [Profiles and configuration](/cli/profiles#settings) to set defaults.

## Output

Commands print tables by default. `-o json` and `-o yaml` print the API's own objects with the API's field names, and lists keep the API's envelope, so the [API reference](/api) describes the output too:

```sh
ezgh projects list
```

```text
ID                                     SLUG               NAME   CREATED
0199a3c2-6c2f-7e51-8a4b-3d9f7c2e5a81   prj_g7h8i9j0k1l2   web    2026-09-28T10:00:00.000Z
```

```sh
ezgh projects list -o json
```

```json
{
  "projects": [
    {
      "id": "0199a3c2-6c2f-7e51-8a4b-3d9f7c2e5a81",
      "organizationId": "0199a3c2-5b1e-7d40-9f3a-2c8e6b1d4f70",
      "name": "web",
      "slug": "prj_g7h8i9j0k1l2",
      "resourceName": "ezgh::org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2",
      "createdAt": "2026-09-28T10:00:00.000Z",
      "updatedAt": "2026-09-28T10:00:00.000Z"
    }
  ],
  "nextCursor": null
}
```

- `--no-headers` leaves the header row out of tables.
- Results go to standard output. Messages, warnings and errors go to standard error.
- A list reads one page. `--limit` sets the page size, `--all` reads every page, and `--cursor` starts from a page's `nextCursor`. When there are more results, a table is followed by a note on standard error, and JSON and YAML have a `nextCursor`.
- `ezgh ocr process` prints the document's text by default; `-o json` and `-o yaml` print the full result.
- Secrets that are shown once, such as a new API key, are printed alone on standard output.

## Global flags

Every command takes these flags:

| Flag | Description | Default |
| --- | --- | --- |
| `--profile` | The [profile](/cli/profiles) to use | `EZGH_PROFILE`, then the default profile, then `default` |
| `--org` | Organization, by ID or slug | `EZGH_ORG`, then the profile's, then the only organization you belong to |
| `--project` | Project, by ID, slug or name | `EZGH_PROJECT`, then the profile's |
| `-o`, `--output` | Output format: `table`, `json` or `yaml` | The profile's, then `table` |
| `--no-headers` | Leave the header row out of tables | No |
| `--timeout` | How long one request may take | `30s` |
| `--debug` | Log each request and response to standard error, without credentials | No |
| `-h`, `--help` | Print the command's help | |

## Confirmations

Commands that delete or remove something ask for confirmation when standard input is a terminal. Otherwise they fail unless you pass `--yes` (`-y`).

## Errors and exit codes

Errors go to standard error with the platform's message and error code, any validation issues, the quota's limit and usage for a quota refusal, and the request ID.

| Exit code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Any other error, including conflicts (`409`) and a precondition failure (`412`) |
| `2` | Bad usage: unknown command or flag, missing or extra argument, invalid value, a profile that doesn't exist |
| `3` | Not authenticated: no credential, or the platform refused it (`401`) |
| `4` | Forbidden: your policies don't allow the request (`403`). `ezgh iam permissions check` also exits `4` when an action is denied |
| `5` | Not found (`404`), or a name that matches nothing |
| `6` | A quota refused the request (`quota_exceeded`) |
| `130` | Interrupted (Ctrl-C) |

`ezgh` retries a request refused with `429` or `503` after the `Retry-After` it gives, up to 4 attempts, when the wait is at most a minute. A `quota_exceeded` refusal is never retried. `ezgh ocr process` retries only when processing couldn't start (`503 capacity_unavailable`), because each processing request is billed.

Source: https://docs.ezghcloud.com/cli/index.mdx