Command reference

Every command group, what it does, and where each one is explained in full.

Every command accepts --help. This page is the index; the pages it links to have the detail, and the terminal is always current.

To install the CLI, see Installing the CLI.

Global flags

These go before the command name:

isogrid --api https://api.isogrid.skyvault.pro apps list

And the environment, for scripts and pipelines:

Things are named by slug, name or id, and flags may come before or after the names: isogrid apps deploy shop --wait and isogrid apps deploy --wait shop are the same command.

Signing in

isogrid login              # opens a browser, approves this machine
isogrid logout [--revoke]  # forgets the credential here; --revoke withdraws it on the server too
isogrid whoami             # who you are, where, and what this credential may do
isogrid orgs list          # the organizations you belong to, and which one is pinned
isogrid auth credentials   # every credential issued for your account
isogrid auth revoke <id>   # revoke one (from a browser session only)

login takes --scope a,b to ask for only some permissions, --name to label the credential, --no-browser to print the address instead of opening it, and --force to replace a credential you already have.

A credential is pinned to one organization: the one you were looking at in the browser when you approved it. There is deliberately no orgs use: a command that appeared to switch and then acted somewhere else would be worse than no command at all. To work elsewhere, switch organizations in the web console and run isogrid login --force.

A credential never holds more than you do. What you approve is a ceiling, checked against your role every time. Some things it can never do: billing, appointing administrators, and minting or revoking credentials. See Roles, permission groups and access.

Revoke anything you do not recognise, and the credential on any machine you no longer control. Revocation takes effect at once.

Applications: isogrid apps

isogrid apps list
isogrid apps get <app> [--exact]
isogrid apps create --name NAME --url REPO_URL|IMAGE_REF [flags]
isogrid apps update <app> [flags] [--deploy [--ref REF]]
isogrid apps build <app> [--ref REF]
isogrid apps deploy <app>
isogrid apps stop <app> | start <app>
isogrid apps status <app>
isogrid apps scale <app> [--replicas N] [--tier SIZE]
isogrid apps tiers <app>
isogrid apps logs <app> [--follow]
isogrid apps env <app>
isogrid apps secrets <app>
isogrid apps delete <app> [--yes]

Creating from GitHub, GitLab or an image, environment and secrets, merging versus replacing, and what --wait counts as a failure: Automating applications.

Deploying from CI/CD: isogrid ci

isogrid ci init github|gitlab [--app NAME] [--cluster REGION] [--output PATH]

Writes a ready-to-commit pipeline that deploys on every push. Minting a credential for it, the full templates, and what to do when a job fails: Deploying from CI/CD.

Repositories: isogrid repos

isogrid repos list
isogrid repos access <repo> --visibility private|administrators|organization|inherit
isogrid repos grant <repo> (--member EMAIL | --group SLUG) --preset NAME
isogrid repos grants <repo>
isogrid repos revoke <repo> <grant>

Members and groups: isogrid iam

isogrid iam members
isogrid iam groups list | get | create | update | delete
isogrid iam groups add-member <group> <email>
isogrid iam groups remove-member <group> <email>
isogrid iam permissions

Both are explained with examples in Repositories, groups and access.

Databases: isogrid database

isogrid database list
isogrid database instances
isogrid database create <name> [--instance ID]

database also answers to db.

Credentials are printed once, when the database is created, and cannot be retrieved afterwards. If you are scripting this, capture the output; if you lose them, create new ones. See Databases.

Regions: isogrid regions

isogrid regions list [--all]

Only regions accepting work are listed by default. A draining region still serves what is already on it but takes nothing new. --all shows everything you have access to.

Documentation: isogrid docs

isogrid docs search <term> [--language en|fr|ar]
isogrid docs show <section>/<slug> [--language en|fr|ar]
isogrid docs list [--section guide]

These work without signing in. docs show prints Markdown as written, so a command copied out of a page is the command. Notices go to standard error, so isogrid docs show guide/databases > databases.md produces a clean file.

The CLI itself

isogrid update [--check]   # replace this executable with the platform's current build
isogrid version

See Installing the CLI.

Output for scripts

Most commands take --json and print the API's response unchanged. Anything a person reads and a script does not — progress, prompts, hints — goes to standard error, so isogrid apps list --json | jq works without filtering noise.

Exit codes: 0 success, 1 failure (including a failed or rolled-back deployment under --wait), 2 a usage error, or a destructive command without --yes and without a terminal to confirm on.

Edge cases worth knowing before you meet them

"not signed in" on a machine you signed in on. Credentials are per endpoint. If you passed --api once, you signed in to that endpoint and the default one is still anonymous.

A permission error the web console does not give you. A CLI credential can be approved with a narrower scope than your account has. isogrid whoami shows what this one carries; isogrid login --force authorises a wider one.

Your credential expired. Sign in again; nothing else is affected.

A command hangs. --follow is meant to stay attached, and --wait waits up to --timeout. Interrupting cancels the request in flight rather than killing the process mid-write, so Ctrl-C is safe.

A script works interactively and fails in CI. Almost always the credential: ISOGRID_TOKEN is not set, or it is pinned to a different organization. Make isogrid whoami the first step of the pipeline. See Deploying from CI/CD.