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.