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
Flag
--api URL The endpoint to use, instead of the one you last signed in to.
--organization SLUG Act in this organization. It must be the one the credential is pinned to.

And the environment, for scripts and pipelines:

Variable
ISOGRID_API_URL Endpoint to use.
ISOGRID_TOKEN Credential to use, instead of the stored one. Never written to disk.
ISOGRID_ORGANIZATION Organization to act in.
ISOGRID_CONFIG_HOME Where to keep config.json. Default ~/.isogrid.
ISOGRID_INSTALL_DIR Where the installers put the binary.
NO_COLOR Disable colour. It is also off whenever output is not a terminal.

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.

Deploying a folder: isogrid deploy

isogrid deploy [PATH] [--name NAME] [--only NAME]... [--public | --private] [flags]
isogrid deploy [PATH] --app APP

Uploads a folder of code, or a .zip of it, and runs it. No repository and no Dockerfile are needed. --app ships a new version of an application deployed this way. See Automating applications.

Applications: isogrid apps

isogrid apps list
isogrid apps get <app> [--exact]
isogrid apps create --name NAME --url REPO_URL|IMAGE_REF [flags]
isogrid apps create --name NAME --external-image REF [--registry NAME] [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 logs <app> --search QUERY [--since 1h] [--limit N]
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.

Among the flags: --worker for an application that listens on no port (--no-worker on update undoes it), and --secret-env and --vault-secret-env (the latter on create) for a secret delivered as an environment variable.

Stack files: isogrid stack

isogrid stack preview (-f FILE|DIR... | --repo REPO [--provider github|gitlab] [--ref REF] --path PATH...)
    [--stack NAME] [--region REGION] [--var KEY=VALUE]... [--var-file PATH] [--json]
isogrid stack apply (-f FILE|DIR... | --repo REPO [--provider github|gitlab] [--ref REF] --path PATH...)
    [--stack NAME] [--var KEY=VALUE]... [--size [FILE:]SERVICE=TIER]...
    [--registry [FILE:]SERVICE=NAME]... [--network [FILE:]SERVICE=NAME]... [--placement [FILE:]SERVICE=CONSTRAINT]...
    [--port [FILE:]SERVICE=N]... [--skip [FILE:]SERVICE]... [--no-deploy] [--wait] [--timeout 20m]

Deploys a docker-compose or docker stack file, one application per service, named <stack>-<service>; applying again updates them. env_file is not read and volumes are not mounted. What is applied, and how placement and registries are chosen: Deploying a stack file.

-f takes a folder, and repeats; --repo/--path read a connected repository instead. With several files --stack is a prefix (<prefix>-<file name>) and FILE:SERVICE=... targets one file.

Container registries: isogrid registries

isogrid registries list
isogrid registries add --name NAME --kind KIND [--host HOST] --username USER --password-stdin [--no-verify]
isogrid registries update <registry> [--name NAME] [--username USER] [--password-stdin]
isogrid registries test <registry>
isogrid registries remove <registry> [--yes]

registries also answers to registry. The password or token is read from standard input or ISOGRID_REGISTRY_PASSWORD, never from a flag. See Other container registries.

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.

Git accounts: isogrid connect

isogrid connect github [--authorize] [--no-browser]
isogrid connect gitlab [--token TOKEN | --token-stdin] [--no-browser] [--nomad CLUSTER [--name NAME]]
isogrid connect status [--json]

Connect your own GitHub or GitLab account to the organization without opening the console. connect github opens GitHub's page for the platform's App; choose the repositories to share, and the terminal waits until the account appears. connect gitlab --token takes a personal, group or project access token (read_api, read_repository) and needs no browser; without --token it opens GitLab's sign-in, when the platform has a GitLab OAuth application. The browser that opens must be signed in to the console as you, in this organization. New connections start private: isogrid repos access opens a repository to others. --nomad CLUSTER keeps a GitLab token on the ISOGrid Nomad agent of that cluster instead of on the platform (isogrid registries add --nomad CLUSTER does the same for a registry): handed over once, stored in your Vault, only the name remembered.

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] [--no-wait] [--timeout 15m]

database also answers to db. database create waits until the database is ready and exits non-zero if provisioning fails, printing the platform's reason; --no-wait returns as soon as it is accepted.

Dedicated instances: isogrid instances

isogrid instances list
isogrid instances get <instance>
isogrid instances create <name> --engine postgres|mysql|mongodb [--topology single|ha] [--nodes 3|5]
                         [--cluster REGION] [--private] [--no-wait] [--timeout 15m]

A database server your organization owns, at the smallest size the region sells, public by default. --topology ha (PostgreSQL only) is a multi-node high-availability cluster: one instance, one endpoint, however many nodes. Like database create, it waits until the instance is running.

Managed services: isogrid services

isogrid services list
isogrid services get <service>
isogrid services create <name> --kind redis|rabbitmq|keycloak|kafka [--cluster REGION] [--private]
                        [--no-wait] [--timeout 15m]

services also answers to svc. Waits until the service is running, the same way.

Credentials are never printed. None of these commands shows a password: the connection details are in the console, where they can be shown again whenever you need them. See Databases.

Networks: isogrid networks

isogrid networks list [--cluster REGION] [--json]

networks also answers to network. Lists the private networks you can create things on: your organization's own, marked as the default, and the ones shared with it. --network on a create command takes any of them.

The gateway: isogrid networks gateway

isogrid networks gateway show   [--network NETWORK] [--cluster REGION] [--live] [--json]
isogrid networks gateway open   [--network NETWORK] [--cluster REGION] [--tunnel-subnet CIDR]
isogrid networks gateway rotate [--network NETWORK] [--cluster REGION] [--yes]
isogrid networks gateway close  [--network NETWORK] [--cluster REGION] [--yes]

VPN access is currently available only to businesses, for their on-premise servers; other accounts are answered that the service is not available yet.

A WireGuard gateway lets your own network - a laptop, an office, a VPC - into a private network, where it reaches your services directly and resolves them by alias. open creates it (the region has to price gateways); show --live asks the cluster for the task's state and each peer's last handshake; rotate gives the gateway new keys, after which every peer must import a fresh configuration; close removes it. Without --network, your organization's own network in the region is used. Only the network's owner can manage its gateway.

Peers: isogrid networks peers

isogrid networks peers list    [--network NETWORK] [--json]
isogrid networks peers add     NAME [--network NETWORK] [--subnet CIDR]... [--out FILE|.]
isogrid networks peers config  NAME [--network NETWORK] [--out FILE|.]
isogrid networks peers rotate  NAME [--network NETWORK] [--out FILE|.] [--yes]
isogrid networks peers disable NAME [--network NETWORK]
isogrid networks peers enable  NAME [--network NETWORK]
isogrid networks peers remove  NAME [--network NETWORK] [--yes]

A peer is one device or one site; a site lists the subnets behind it with --subnet (repeatable). add prints the peer's WireGuard configuration - or writes it with --out (. for the suggested file name) - ready to import; it contains the peer's private key, so fetch it again with config rather than keeping copies. rotate replaces one peer's keys and prints the new configuration; the old one stops working. disable keeps a peer out without deleting it. Every change waits for the platform to apply it, so commands can be chained in a script.

Devices: isogrid networks devices

isogrid networks devices list        [--kind lb|router|switch|nat|site] [--json]
isogrid networks devices show        DEVICE [--live] [--json]
isogrid networks devices example     KIND
isogrid networks devices create      KIND NAME [--network NETWORK] [--cluster REGION] [--config FILE|-]
                                     [--backend HOST:PORT]... [--port N] [--protocol http|tcp] [--public]
isogrid networks devices update      DEVICE [--name NAME] [--config FILE|-]
isogrid networks devices delete      DEVICE [--yes]
isogrid networks devices site-config DEVICE [--out FILE|.]
isogrid networks devices rotate      DEVICE [--yes]

Load balancers, routers, switches, NAT gateways and site-to-site gateways (see the Network devices guide). A device's settings are one JSON object: example KIND prints one to start from, create and update take it with --config. In it, a router names networks by slug (from_network, to_network) and a switch names applications (application); the CLI turns them into ids. A one-listener load balancer needs no file: create lb web --backend acme-api:8000. show --live asks the cluster for the running copies, each backend's health and a tunnel's last handshake. Every change waits for the platform to apply it; --no-wait returns at once. site-config and rotate are for site-to-site gateways only, which are available to businesses only.

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; the API itself is described in REST API. 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.