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

> ## Agent Instructions
> If you are an AI assistant asked to build, change or ship a Gliss app, read the For AI agents page first (/for-ai-agents.md on this site) and follow its steps.
> Inside an app's folder, the app's own AGENTS.md is the authority; `gliss guide` prints it. Never ask the user for a secret's value.

# gliss CLI

> Commands of the gliss client: sign in, release, status, diagnosis, logs and the MCP server.

> [!NOTE]
>
> **Coming in the first release.** This page describes behaviour being built for the first Gliss release. Details may change before it ships.

The `gliss` client is one signed program for Windows, macOS and Linux (x64 and Arm), installed for your user without admin rights. This page lists the commands of the first release. Commands still being designed are at the end, under [Planned](#planned).

## Install and update

The install scripts download a release, check its signature and checksum, and only then put `gliss` in place.

> [!NOTE]
>
> The install commands work once the first release is published. The address will move to a branded host, `get.glissando.dev`; until then it is the release bucket below.

```sh theme={null}
# macOS and Linux: into ~/.local/bin
curl -fsSL https://gliss-releases-569486438045.s3.eu-central-1.amazonaws.com/cli/install.sh | sh

# Windows (PowerShell 5.1 or 7): into %LOCALAPPDATA%\Programs\gliss
irm https://gliss-releases-569486438045.s3.eu-central-1.amazonaws.com/cli/install.ps1 | iex
```

`sh -s -- --version 0.2.0 --dir ~/bin` installs a given version into another folder.

To read the script before it runs, download it, inspect it, then run it:

```sh theme={null}
# macOS and Linux
curl -fsSLO https://gliss-releases-569486438045.s3.eu-central-1.amazonaws.com/cli/install.sh
less install.sh
sh install.sh

# Windows (PowerShell)
Invoke-WebRequest https://gliss-releases-569486438045.s3.eu-central-1.amazonaws.com/cli/install.ps1 -OutFile install.ps1
notepad install.ps1
Get-Content -Raw install.ps1 | Invoke-Expression
```

| Command | What it does |
| - | - |
| `gliss update` | Replace `gliss` with the newest signed release. `--version V` installs that version (never an older one); `--check` only says whether a newer release exists |
| `gliss version` | Show the version, commit and platform |

## Sign in

| Command | What it does |
| - | - |
| `gliss login` | Sign in with your company account, in the browser |
| `gliss whoami` | Show who the client is signed in as, on which control plane |
| `gliss logout` | End the session, on this machine and on Gliss |

`gliss login` prints an address and a code and opens the page in your browser. Type the code there and approve. Approve only a sign-in you just started yourself.

| Flag | Meaning |
| - | - |
| `--api URL` | The Gliss console to sign in to. Defaults to the last one you used, then to the release's built-in address |
| `--org ID` | Your default organization, for app names that exist in more than one of your organizations (see [App names](#app-names)) |
| `--no-browser` | Print the address only |
| `--insecure-file` | Keep the session in a file only you can read, instead of the OS keychain. For machines without a keychain |

The session is kept in your OS keychain. It renews itself, lasts up to 14 days, and ends after 7 days without use; then run `gliss login` again. You can also sign it out in the console, under Settings, Signed-in CLIs.

## Your apps

| Command | What it does |
| - | - |
| `gliss apps` | List the apps you can see: name, organization, cluster, and each stage's health. `--org ID` lists one organization |

You see an app once it has a Beta or Live stage, once you hold a role on it, or once you have a Preview of it. Organization admins see every app. Create a new one with [`gliss create`](#new-apps-and-ai-guidance).

### App names

The commands below take an app's **name**, the `app:` in its `gliss.yaml`. A name is unique within an organization. If you belong to several organizations and the name exists in more than one, the command stops and lists them: choose one with `--org ID`, the `GLISS_ORG` variable, or a default from `gliss login --org`. `gliss release` always checks your current apps when no organization is chosen, so it stops even for a name that appeared in a second organization moments ago; reading commands may use a list up to an hour old. If the name is not found, the command lists the apps you can see.

## New apps and AI guidance

| Command | What it does |
| - | - |
| `gliss create <name>` | Create an app: Gliss makes its repository in your organization's GitHub from the Gliss template, and then your work branch `gliss/u/<handle>`. Any member may. `--org ID` picks the organization; `--wait 3m` is how long to wait for the repository (`0`: don't wait); `gliss create --status <id>` checks on a creation it printed |
| `gliss init [name]` | Write a new app from the template into `./<name>`, or the current folder: `gliss.yaml`, a backend and frontend, CI, `PROMPT.md` and the AI guidance. `--dir` picks the folder, `--owner` the owner's work email (default: Git's `user.email`) |
| `gliss guide` | Print `AGENTS.md`, the guidance for your AI. `--write` writes or refreshes the guidance files in the app's folder (only files Gliss wrote, and only its own block in `CLAUDE.md`); `--check` exits `1` if one is missing or out of date; `--show FILE` prints one; `--dir` picks the folder |

App names are lower-case letters, digits and hyphens, starting with a letter. The guidance files are listed in [Supported AI tools](https://docs.glissando.dev/build/ai-tools.md#the-guidance-in-every-app).

## Release and check

| Command | What it does |
| - | - |
| `gliss release <app> --stage beta` | Build the app's images, push them, ask Gliss to release them to Beta, and follow the release |
| `gliss release <app> --stage preview` | The same, to your own Preview |
| `gliss status <app>` | Each stage: release and commit, health, ready and desired replicas, URL, last result, when the release's approval expires |
| `gliss diagnose <app> --stage <stage>` | What is wrong, whether it is the app's problem or the platform's, and the next step |
| `gliss logs <app> --stage <stage>` | Container logs, with secrets removed |

Live is never released from the client: Publish, in the console, promotes what Beta runs.

### `gliss release`

Run it in the app's folder, a Git work tree with `gliss.yaml`. It releases the **committed** code at `HEAD` and refuses a work tree with uncommitted changes.

> [!WARNING]
>
> **For now, `gliss release` builds on your machine.** It needs Docker with buildx, and the AWS CLI with a profile that may push to your cluster's image registry (ask your IT team). Use a profile limited to pushing to that registry, not an administrator profile: `gliss release` checks the profile's account, but anything else running as you can use the profile too. Building in your app's CI or in Gliss, with no Docker or cloud credentials on your machine, is planned.

| Flag | Meaning |
| - | - |
| `--stage` | `beta` or `preview` (required) |
| `--instance NAME` | For a Preview: whose. Default: yours |
| `--dir PATH` | The app's folder. Default: the current folder |
| `--aws-profile NAME` | The AWS profile that pushes the images. Default: the AWS CLI's. Use a profile that may only push to your cluster's image registry, not an administrator profile |
| `--wait DURATION` | How long to follow the release in the cluster. Default `15m`; `0` returns once Gliss has approved it |
| `--allow-dirty` | Release `HEAD` although there are uncommitted changes (they are not built) |
| `--no-build --image COMPONENT=REPOSITORY@sha256:DIGEST` | Release images built elsewhere, one `--image` per component |
| `--org ID` | See [App names](#app-names) |
| `--registry HOST` | The cluster's registry. Only with an app token, which cannot read the cluster (see [Tokens](#tokens-for-ci-and-scripts)) |

If Gliss declines the release, it prints each reason in plain language and nothing is deployed. Fix `gliss.yaml` and release again. If the release fails in the cluster, it prints the diagnosis.

Exit codes: `0` released, `1` an error, `2` a wrong command, `3` declined or failed in the cluster, `4` still running when the wait ran out (check with `gliss status`).

### `gliss status`, `gliss diagnose`, `gliss logs`

| Flag | Commands | Meaning |
| - | - | - |
| `--stage` | all | `preview`, `beta` or `live`. Required for `diagnose` and `logs`; `status` shows every stage without it |
| `--instance NAME` | all | For a Preview: whose |
| `--org ID` | all | See [App names](#app-names) |
| `--since` | `diagnose`, `logs` | How far back: `15m`, `2h`, or a time; `diagnose` also takes `1d` |
| `--component NAME` | `logs` | One component from `gliss.yaml` |
| `--pod NAME` | `logs` | One pod |
| `--previous` | `logs` | The container before its last restart |
| `--tail N` | `logs` | Lines per container. Default 200, at most 5000 |

`gliss diagnose` exits with `3` when the stage is failing.

## Your AI tool: `gliss mcp`

`gliss mcp` runs the Gliss tools for your AI tool (an MCP server on standard input and output). It uses your `gliss login` session. In Claude Code:

```sh theme={null}
claude mcp add gliss -- gliss mcp
```

In Cursor, Codex or Claude Desktop, add a server with the command `gliss mcp`; see [Supported AI tools](https://docs.glissando.dev/build/ai-tools.md#connect-the-gliss-tools).

| Tool | What it does |
| - | - |
| `gliss_status` | As `gliss status` |
| `gliss_diagnose` | As `gliss diagnose` |
| `gliss_logs` | As `gliss logs` |
| `gliss_release` | As `gliss release`, only when you start the server with `--allow-release` |

| Flag | Meaning |
| - | - |
| `--allow-release` | Offer `gliss_release` for Beta and your Preview; `--allow-release=preview` for your Preview only |
| `--dir PATH` | With `--allow-release`: the app folder the AI may release. You fix it here; the AI cannot choose another |
| `--aws-profile NAME` | With `--allow-release`: the AWS profile that pushes |
| `--org ID` | See [App names](#app-names) |

> [!WARNING]
>
> `gliss_release` changes what runs at a stage. Your AI tool asks you before each call; never allowlist or auto-approve it.

Logs and error messages from your app are marked to your AI as untrusted text, which it must not follow as instructions.

## Tokens for CI and scripts

Without `gliss login`, the client uses a token from the environment.

| Variable | Meaning |
| - | - |
| `GLISS_TOKEN` | An app token (made for one app in the console) or a personal token. Overrides `gliss login` |
| `GLISS_API_URL` | The Gliss console's address. Needed with `GLISS_TOKEN` |
| `GLISS_ORG` | The organization for app names, as `--org` |
| `GLISS_APPS` | `name=app-id,...`: the app ids to use, instead of looking the names up. Rarely needed |
| `GLISS_REGISTRY` | The cluster's registry, as `--registry`. Only with an app token |
| `GLISS_CONFIG_DIR` | Where the client keeps its settings. Default: your user configuration folder |

An app token works only for its app, and cannot read the cluster, so `gliss release` with one needs `--registry` (the cluster's page in the console shows it). After `gliss login` none of these are needed.

## Planned

These commands are designed but not built yet. Details may change.

| Command | What it will do |
| - | - |
| `gliss clone <app>` | Clone an app's repository and set up Git access and your work branch, with no GitHub account needed |
| `gliss open` | Open the app in the console |
| `gliss dev` | Sync saved changes to your Preview in seconds |
| `gliss share` | Share your work to Beta |
| `gliss publish` | Publish Beta to Live |
| `gliss status --wait` | Wait for the current release |
| `gliss secret set NAME` | Set a secret value yourself |
| `gliss preview url --signed` | A signed Preview link for tools that cannot sign in |
| `gliss test` | Run a component's `test` command in Preview |
| `--json` on `status`, `logs` and `diagnose` | Output for your AI and scripts |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.