Command reference
Every gigadrive command, subcommand, argument and flag, with the exact long names and aliases.
Every command the gigadrive binary accepts, with its exact arguments and flags. The alias gn
works everywhere gigadrive does.
Every command
Listed in the order gigadrive --help prints them.
| Command | What it does |
|---|---|
gigadrive login | Sign in with the OAuth 2.0 device grant |
gigadrive logout | Delete the stored credential |
gigadrive whoami | Print the OpenID Connect userinfo response as JSON |
gigadrive link | Link the current directory to an application |
gigadrive unlink | Remove the current directory's link |
gigadrive apps list | List applications you can access |
gigadrive apps create | Create an application |
gigadrive domains list | List an application's custom domains |
gigadrive domains add | Attach a custom domain |
gigadrive domains update | Change what a custom domain serves |
gigadrive domains claim | Move a hostname from another organization |
gigadrive domains inspect | Print one custom domain and its DNS records |
gigadrive domains check | Check a custom domain's DNS records now |
gigadrive domains rm | Remove a custom domain |
gigadrive domains owners | List, add, verify and remove the organization's verified domains |
gigadrive env list | List environment variables in the resolved scope |
gigadrive env set | Create an environment variable |
gigadrive env rm | Delete an environment variable by key or ID |
gigadrive env pull | Write non-sensitive variables to a local dotenv file |
gigadrive deployments list | List deployments |
gigadrive deployments inspect | Print one deployment and its hostnames |
gigadrive ai usage summary | Print AI Gateway usage totals as JSON |
gigadrive ai usage requests | List AI Gateway request events |
gigadrive ai usage export | Export AI Gateway usage as CSV |
gigadrive ai budgets get | Print the organization's AI Gateway budgets as JSON |
gigadrive ai budgets set | Replace the organization's AI Gateway budgets |
gigadrive ai policies get | Print the AI Gateway policy as JSON |
gigadrive ai policies set | Replace the AI Gateway policy |
gigadrive ai models list | List models the gateway routes to |
gigadrive ai models get | Print one model's full record as JSON |
gigadrive ai chat | Send a single prompt through the AI Gateway |
gigadrive microvms create | Create a microVM and wait until it runs |
gigadrive microvms ls | List microVMs |
gigadrive microvms get | Print one microVM and its preview URLs |
gigadrive microvms metrics | Show a microVM's CPU, memory and disk use |
gigadrive microvms exec | Run a command in a microVM |
gigadrive microvms shell | Open an interactive shell in a microVM |
gigadrive microvms cp | Copy files between your machine and a microVM |
gigadrive microvms stop | Stop microVMs |
gigadrive microvms rm | Delete microVMs, stopping them first |
gigadrive microvms extend | Set how long a microVM keeps running, counted from now |
gigadrive microvms images ls | List built-in and custom images |
gigadrive microvms images create | Build a custom image from a registry image or a Dockerfile |
gigadrive microvms images rm | Delete a custom image |
gigadrive microvms volumes ls | List the application's volumes |
gigadrive microvms volumes create | Create an empty volume |
gigadrive microvms volumes save | Save a running microVM's volumes without stopping it |
gigadrive microvms volumes rm | Delete a volume and its contents |
gigadrive microvms webhooks ls | List the application's microVM webhooks |
gigadrive microvms webhooks add | Add a webhook and print its signing secret |
gigadrive microvms webhooks rm | Delete a webhook |
gigadrive vm | Alias of gigadrive microvms, with the same subcommands |
gigadrive build | Run a production install and build in the current directory |
gigadrive debug config | Print the resolved project configuration |
gigadrive deploy | Deploy the current directory |
gigadrive platform deploy | Legacy alias for gigadrive deploy |
gigadrive setup | Link, pull variables and provision local API credentials in one step |
Conventions
Every command and subcommand also accepts --help / -h, --version, --wizard,
--completions <shell> and --log-level <level>, described in the CLI overview.
Boolean flags have no negated form, so --no-yes and --no-sensitive do not exist. Omitting the
flag is how you turn it off.
Running a group on its own, such as gigadrive env or gigadrive ai usage, prints nothing and
exits 0. An unknown subcommand at any depth exits 1 and names the root command, not the group you
typed, so gigadrive apps bogus reports
Invalid subcommand for gigadrive - use one of 'login', 'logout', ....
Authentication
gigadrive login, gigadrive logout and gigadrive whoami take no arguments and no options. See
Authentication.
Project link
gigadrive link
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Application ID to link (skips the interactive picker) |
--org | -o | no | Only list applications belonging to this organization ID |
gigadrive unlink
No arguments, no options. Details in Project linking.
Applications
gigadrive apps list
| Flag | Alias | Required | Description |
|---|---|---|---|
--org | -o | no | Only list applications belonging to this organization ID |
Prints <id> <name> (<organization>) per line, then a count. An empty result prints
No applications found.
gigadrive apps create
| Flag | Alias | Required | Description |
|---|---|---|---|
--org | -o | yes | Organization ID that will own the application |
--name | -n | yes | Application display name |
--slug | no | Optional lowercase application slug | |
--root-directory | no | Optional project directory relative to the repository root |
gigadrive apps create --org 0195c0aa-0000-7000-8000-0000000000ff --name "Marketing site"
gigadrive apps create -o 0195c0aa-0000-7000-8000-0000000000ff -n "API" --slug api --root-directory apps/apiCustom domains
gigadrive domains has its own page with every flag and example: Custom domains.
Environment variables
--org switches these commands to organization scope. Without it they use --app, and without that
the linked application.
gigadrive env list
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Operate on this application (overrides the linked application) |
--org | -o | no | Operate on this organization instead of an application |
Prints KEY=value per line. Sensitive variables print as KEY=***.
gigadrive env set
| Argument | Required | Description |
|---|---|---|
key=value | yes | Variable assignment, e.g. DATABASE_URL=postgres://user:pass@host/db |
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Operate on this application (overrides the linked application) |
--org | -o | no | Operate on this organization instead of an application |
--sensitive | no | Store the value as sensitive (hidden in API responses) | |
--env | -e | no | Environment ID for an environment-scoped variable (application scope only) |
The argument splits at the first =, so values may contain further = characters. A missing or
leading = reports
Invalid format. Use KEY=VALUE, e.g. "gigadrive env set DATABASE_URL=postgres://...".
gigadrive env rm
| Argument | Required | Description |
|---|---|---|
key-or-id | yes | Variable key or ID to remove |
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Operate on this application (overrides the linked application) |
--org | -o | no | Operate on this organization instead of an application |
Matches on ID or key. There is no confirmation prompt.
gigadrive env pull
Application scope only. This command has no --org.
| Argument | Required | Description |
|---|---|---|
file | no | Output file to write (default: .env.local) |
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Operate on this application (overrides the linked application) |
--environment | -e | no | Environment slug to resolve overrides for (e.g. preview). Omit for the local baseline |
--yes | -y | no | Overwrite an existing file without confirmation |
--with-credentials | no | Also provision API-key credentials so the local app can call the API as this application | |
--rotate | no | Force a fresh API key when provisioning credentials, revoking the previous one |
Only non-sensitive values come back. Withheld secrets are reported as
Skipped <n> sensitive variable(s); secrets live only in production/preview environments.
The -e alias means two different things
On env set, -e is --env and takes an environment ID. On env pull and setup, -e is --environment and
takes an environment slug such as preview. Spell the long form out in scripts.
Deployments
gigadrive deploy
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Application ID to deploy to (overrides the linked application) |
--org | -o | no | Organization ID to use when automatically creating an application |
--name | -n | no | Application name to use when automatically creating an application |
gigadrive platform deploy is the same command under a legacy name, with the same three flags. Full
behaviour is on Deploy.
gigadrive deployments list
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Filter by application ID (defaults to the linked application) |
--org | -o | no | Filter by organization ID |
--status | -s | no | Filter by deployment status |
--status accepts exactly one of:
| Value | Meaning |
|---|---|
PENDING | Created, waiting for artifact upload |
QUEUED | Queued for processing |
STARTING | Processing is starting |
BUILDING | Build pipeline is running |
PROVISIONING | Infrastructure is being provisioned |
ACTIVE | Successfully deployed and serving traffic |
FAILED | Build or provisioning failed |
With no --app in an unlinked directory, no application filter is applied at all.
gigadrive deployments inspect
| Argument | Required | Description |
|---|---|---|
deployment-id | yes | The deployment ID to inspect |
No options. Prints the ID, application, status, timestamps and, when there are any, the deployment's hostnames.
Local development
gigadrive setup
Links the directory if needed, pulls the application's non-sensitive variables, provisions API
credentials and writes everything to one file. Credentials are always provisioned, so there is no
--with-credentials flag here.
| Argument | Required | Description |
|---|---|---|
file | no | Output file to write (default: .env.local) |
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Application ID to set up (skips the interactive picker) |
--org | -o | no | Only list applications belonging to this organization ID when picking |
--environment | -e | no | Environment slug to resolve overrides for (e.g. preview) |
--yes | -y | no | Overwrite an existing file without confirmation |
--rotate | no | Force a fresh API key, revoking the previous one |
An already linked directory ignores --app and --org, and says so:
Note: this directory is already linked to <id>; ignoring --app/--org. Run "gigadrive unlink" first to target a different application.
gigadrive build
No arguments, no options. Runs a production install and build in the current directory, using the
package manager implied by the lock file, with NODE_ENV=production set. It needs a package.json
with a build script, or it stops with No package.json found or
No build script found in package.json.
AI Gateway
--org defaults to the organizationId in the project link. Without either, these commands report
No organization is linked. Pass --org <id> or re-run "gigadrive link".
gigadrive ai usage summary and gigadrive ai usage requests
| Flag | Alias | Required | Description |
|---|---|---|---|
--org | -o | no | Organization ID (defaults to the linked organization) |
--app | -a | no | Restrict to this application ID |
--from | no | Include usage at or after this ISO 8601 timestamp | |
--to | no | Include usage before or at this ISO 8601 timestamp |
summary prints JSON. requests prints one line per event and a count.
gigadrive ai usage export
The four shared usage options also apply, plus:
| Flag | Alias | Required | Description |
|---|---|---|---|
--out | no | Write the CSV to this file instead of stdout |
gigadrive ai usage export --from 2026-07-01T00:00:00Z --to 2026-08-01T00:00:00Z --out july.csvgigadrive ai budgets get
| Flag | Alias | Required | Description |
|---|---|---|---|
--org | -o | no | Organization ID (defaults to the linked organization) |
gigadrive ai budgets set
| Flag | Alias | Required | Description |
|---|---|---|---|
--org | -o | no | Organization ID (defaults to the linked organization) |
--file | -f | no | Path to a JSON file, or "-" for stdin (default: stdin) |
Accepts a bare JSON array or an object shaped { "budgets": [...] }, and replaces the whole budget
set. An empty array clears every budget.
gigadrive ai policies get
| Flag | Alias | Required | Description |
|---|---|---|---|
--org | -o | no | Organization ID (defaults to the linked organization) |
--app | -a | no | Restrict to this application ID |
Prints the policy as JSON, or the line No policy set.
gigadrive ai policies set
| Flag | Alias | Required | Description |
|---|---|---|---|
--org | -o | no | Organization ID (defaults to the linked organization) |
--file | -f | no | Path to a JSON file, or "-" for stdin (default: stdin) |
There is no --app here. Target an application by putting "applicationId" inside the JSON body.
gigadrive ai models list
No arguments, no options. Prints <id> <name> (ctx <contextWindow>) per line.
gigadrive ai models get
| Argument | Required | Description |
|---|---|---|
model-id | yes | The model ID, e.g. openai/gpt-4o |
No options.
gigadrive ai chat
| Argument | Required | Description |
|---|---|---|
prompt | yes | The prompt text, or "-" to read from stdin |
| Flag | Alias | Required | Description |
|---|---|---|---|
--model | -m | yes | The model ID to use, e.g. openai/gpt-4o |
--stream | no | Stream the response token by token |
Sends exactly one user message. There is no system prompt, temperature or max-tokens flag.
gigadrive ai chat "Summarise this changelog" --model openai/gpt-4o
gigadrive ai chat - --model openai/gpt-4o --stream < CHANGELOG.mdmicroVMs
gigadrive vm is an alias of gigadrive microvms and takes the same subcommands. See
microVMs for worked examples.
Durations such as --timeout and the extend argument need a unit, for example 90s, 10m or
2h. A bare number is refused.
gigadrive microvms create
No arguments.
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Application ID (defaults to the linked application) |
--image | -i | no | Image name or ID, built-in or custom (default: node22) |
--vcpus | no | Number of vCPUs: 1, 2 or 4 (default: 1) | |
--memory | no | Memory in MiB (default: 2048) | |
--disk | no | Disk in MiB (default: 10240) | |
--timeout | -t | no | Lifetime before it stops automatically, at most 24h (default: 5m) |
--port | -p | no | Port to expose on a preview URL (repeatable, up to 8) |
--private-previews | no | Answer preview URLs only to requests that carry the preview token printed at create | |
--env | -e | no | Environment variable as KEY=VALUE (repeatable) |
--metadata | -m | no | Metadata as KEY=VALUE (repeatable) |
--deny-egress | no | Block all outbound network traffic | |
--allow-egress | no | Only reach this domain name or public IPv4 network, such as api.openai.com, *.github.com or 140.82.112.0/20 (repeatable, up to 32). See Outbound traffic | |
--inject | no | Add a header to HTTPS requests to a domain, as DOMAIN:HEADER=VALUE (repeatable, up to 8 domains). See Credential injection | |
--inject-file | no | Read --inject rules from a file, one DOMAIN:HEADER=VALUE per line (/dev/stdin for a pipe), so the values stay out of the command line | |
--pause-on-timeout | no | Pause the microVM when its timeout ends instead of stopping it | |
--auto-resume | no | Resume the paused microVM when a command, file call or public preview request reaches it | |
--volume | -v | no | Attach a volume as NAME:PATH, by name or ID (repeatable, up to 4) |
--region | no | Region to place the microVM in | |
--json | no | Print the result as JSON |
--deny-egress cannot be combined with --allow-egress, --inject or --inject-file. In an --inject-file, blank lines and lines starting with # are skipped.
gigadrive microvms create --image python3.13 --vcpus 2 --memory 4096 --port 8000 --timeout 30mgigadrive microvms ls
No arguments. Leaves out stopped and failed microVMs unless you pass --all or --status.
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Application ID (defaults to the linked application) |
--status | -s | no | Only microVMs in this status |
--all | no | Include stopped and failed microVMs | |
--limit | no | Show at most this many (default: 50) | |
--json | no | Print the result as JSON |
gigadrive microvms get
| Argument | Required | Description |
|---|---|---|
microvm-id | yes | The microVM ID |
| Flag | Alias | Required | Description |
|---|---|---|---|
--json | no | Print the result as JSON |
gigadrive microvms metrics
| Argument | Required | Description |
|---|---|---|
microvm-id | yes | The microVM ID |
| Flag | Alias | Required | Description |
|---|---|---|---|
--window | no | Minutes of CPU history, 1 to 1440 (default 15) | |
--json | no | Print the result as JSON |
gigadrive microvms exec
| Argument | Required | Description |
|---|---|---|
microvm-id | yes | The microVM ID |
command | yes | The command and its arguments, after --. One quoted argument runs through /bin/sh -c |
| Flag | Alias | Required | Description |
|---|---|---|---|
--cwd | -w | no | Working directory inside the microVM |
--env | -e | no | Environment variable as KEY=VALUE (repeatable) |
--user | -u | no | Run as this user (default: the image user) |
--sudo | no | Run as root | |
--timeout | -t | no | Kill the command after this long |
--interactive | -i | no | Forward local stdin to the command |
Exits with the command's exit code, or 128 plus the signal number when a signal ended it.
gigadrive microvms exec 0199a7c4-5b1e-7c3d-9f20-333333333333 --timeout 10m -- npm testgigadrive microvms shell
| Argument | Required | Description |
|---|---|---|
microvm-id | yes | The microVM ID |
| Flag | Alias | Required | Description |
|---|---|---|---|
--shell | no | Program to run instead of the login shell, such as python3 | |
--cwd | -w | no | Working directory inside the microVM |
--user | -u | no | Run as this user (default: the image user) |
Needs an interactive terminal and fails without one. Use exec in scripts.
gigadrive microvms cp
| Argument | Required | Description |
|---|---|---|
source | yes | Local path or vm:<id>:<path> |
target | yes | Local path or vm:<id>:<path> |
No options. Exactly one side must be a microVM path. Directories are copied recursively.
gigadrive microvms stop, gigadrive microvms rm
| Argument | Required | Description |
|---|---|---|
microvm-id | yes | One or more microVM IDs |
No options. stop discards each microVM's disk and memory. rm stops each one first if it is
still running, then deletes it.
gigadrive microvms extend
| Argument | Required | Description |
|---|---|---|
microvm-id | yes | The microVM ID |
duration | yes | New remaining lifetime from now, such as 30m |
No options. Prints the new time the microVM stops at.
gigadrive microvms network
Changes what a running or paused microVM may reach. Connections the new rules no longer allow are closed.
| Argument | Required | Description |
|---|---|---|
microvm-id | yes | The microVM ID |
| Flag | Required | Description |
|---|---|---|
--deny-egress | one of three | Block all outbound network traffic |
--allow-egress | one of three | Only reach this domain name or public IPv4 network (repeatable, up to 32) |
--allow-all-egress | one of three | Reach the whole internet again; private networks stay blocked |
--inject | no | Add a header to HTTPS requests to a domain, as DOMAIN:HEADER=VALUE (repeatable, up to 8 domains). Replaces the current rules |
--inject-file | no | Read --inject rules from a file, one per line (/dev/stdin for a pipe) |
--clear-inject | no | Remove every header rule |
Pass exactly one of --deny-egress, --allow-egress or --allow-all-egress. Without --inject or --clear-inject the header rules stay as they are, and --deny-egress removes them. --inject or --inject-file and --clear-inject cannot be combined with each other or with --deny-egress.
gigadrive microvms network 0199a7c4-5b1e-7c3d-9f20-333333333333 --allow-egress registry.npmjs.org --allow-egress '*.github.com'gigadrive microvms images ls
No arguments.
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Application ID (defaults to the linked application) |
--json | no | Print the result as JSON |
gigadrive microvms images create
| Argument | Required | Description |
|---|---|---|
name | yes | Image name: lowercase letters, digits, ., _ and - |
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Application ID (defaults to the linked application) |
--from | no | Public linux/amd64 registry image, such as python:3.13 | |
--dockerfile | -f | no | Path to a Dockerfile to build instead |
--wait | no | Wait until the build finished | |
--json | no | Print the result as JSON |
Pass exactly one of --from and --dockerfile.
gigadrive microvms images create py-ml --from python:3.13 --waitgigadrive microvms images rm
| Argument | Required | Description |
|---|---|---|
image | yes | Image ID or name |
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Application ID (defaults to the linked application) |
gigadrive microvms volumes ls
No arguments.
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Application ID (defaults to the linked application) |
--json | no | Print the result as JSON |
gigadrive microvms volumes create
| Argument | Required | Description |
|---|---|---|
name | yes | Lowercase letters, digits and -, unique within the application |
| Flag | Alias | Required | Description |
|---|---|---|---|
--size | no | Size in MB, 1024 to 51200 (default: 10240) | |
--app | -a | no | Application ID (defaults to the linked application) |
--json | no | Print the result as JSON |
Attach the volume with gigadrive microvms create --volume <name>:<path>. See Volumes.
gigadrive microvms volumes create npm-cache --size 20480gigadrive microvms volumes rename, save, rm
rename <volume-id> <name> renames a volume, save <microvm-id> saves a running microVM's volumes without stopping it, and rm <volume-id> deletes a volume that no microVM holds.
gigadrive microvms webhooks ls
No arguments.
| Flag | Alias | Required | Description |
|---|---|---|---|
--app | -a | no | Application ID (defaults to the linked application) |
--json | no | Print the result as JSON |
gigadrive microvms webhooks add
| Argument | Required | Description |
|---|---|---|
url | yes | HTTPS URL on a public host |
| Flag | Alias | Required | Description |
|---|---|---|---|
--event | no | Event to send, repeatable. Without it, every event is sent | |
--description | no | A note for yourself | |
--app | -a | no | Application ID (defaults to the linked application) |
--json | no | Print the result as JSON |
Prints the signing secret once. See Webhooks for the events and how to verify a request.
gigadrive microvms webhooks add https://example.com/hooks/microvms --event microvm.stopped --event microvm.failedgigadrive microvms webhooks enable, disable, rotate-secret, deliveries, rm
| Argument | Required | Description |
|---|---|---|
webhook-id | yes | The webhook ID |
enable and disable turn event delivery on and off, rotate-secret prints a new signing secret and retires the old one, deliveries lists the 50 most recent deliveries (with --json to print them as JSON), and rm deletes the webhook.
Diagnostics
gigadrive debug config
No arguments, no options. Prints the path of the config file it found, or null when the
configuration came entirely from framework detection, followed by the normalized configuration as
JSON.
Environment variables the CLI reads
| Variable | Default | Effect |
|---|---|---|
GIGADRIVE_API_BASE_URL | https://api.gigadrive.network | API host the client calls, and the value written into generated dotenv files |
GIGADRIVE_BEARER_TOKEN | unset | Access token for non-interactive use |
GIGADRIVE_CLIENT_ID | unset | API key ID for non-interactive use |
GIGADRIVE_CLIENT_SECRET | unset | API key secret for non-interactive use |
GIGADRIVE_REFRESH_TOKEN | unset | Refresh token for non-interactive use |
GIGADRIVE_NETWORK_OAUTH_ISSUER_URL | https://idp.gigadrive.de | Issuer used for OpenID Connect discovery at login |
GIGADRIVE_NETWORK_OAUTH_CLIENT_ID | the first-party CLI client | OAuth client ID used for the device grant |
Setting any one of the four non-interactive variables makes the CLI ignore the stored login entirely.