Environment variables

Read and write environment variables with gigadrive env, and pull a working .env file with optional API credentials.

gigadrive env manages the variables Gigadrive Network injects into your builds and Functions. It also writes a local .env file, optionally carrying credentials that let code on your laptop call the API as the application.

Choosing a scope

list, set and rm act on one application or on one organization.

Flags	Scope
`--org <id>`, `-o`	That organization. Wins over `--app` when both are given
`--app <id>`, `-a`	That application, overriding the linked one
Neither	The application recorded in `.gigadrive/project.json`

With no flag and no link, the command fails and tells you to run gigadrive link, described in Project linking. Organization variables are inherited by every application in the organization, and Variable scopes explains how the layers resolve.

Listing

gigadrive env list

NODE_ENV=production
DATABASE_URL=***
LEGACY_FLAG=

*** means the variable is sensitive and the API will not return its value. Nothing after the = means the stored value is null.

Setting

gigadrive env set takes one KEY=VALUE argument and splits it at the first =, so a value containing further = characters survives intact. A missing =, or one in first position, is rejected.

Flag	Alias	Description
`--app`	`-a`	Operate on this application (overrides the linked application)
`--org`	`-o`	Operate on this organization instead of an application
`--sensitive`		Store the value as sensitive (hidden in API responses)
`--env`	`-e`	Environment ID for an environment-scoped variable (application scope only)

gigadrive env set DATABASE_URL=postgres://app:s3cret@db.internal:5432/app --sensitive

Use --sensitive for anything you would not want printed back to a terminal. The value is accepted and then never returned by the API again, which also means env pull stops writing it. Sensitive values covers the rest.

--env binds a variable to a single environment and is dropped in organization scope.

gigadrive env set FEATURE_CHECKOUT_V2=on --env 0195c0bb-0000-7000-8000-000000000001

Removing

gigadrive env rm FEATURE_CHECKOUT_V2

The CLI lists the variables in scope and deletes the first one whose ID or key matches the argument. A miss prints No environment variable matching "FEATURE_CHECKOUT_V2". There is no confirmation prompt. The --app and --org flags select the same scopes as they do for gigadrive env set.

Pulling a local file

gigadrive env pull always targets an application, so it takes no --org.

Argument or flag	Alias	Description
`file`		Output file to write (default: `.env.local`)
`--app`	`-a`	Operate on this application (overrides the linked application)
`--environment`	`-e`	Environment slug to resolve overrides for (e.g. preview). Omit for the local baseline
`--yes`	`-y`	Overwrite an existing file without confirmation
`--with-credentials`		Also provision API-key credentials so the local app can call the API as this application
`--rotate`		Force a fresh API key when provisioning credentials, revoking the previous one

Watch the alias: -e is --env, an environment ID, on set, and --environment, an environment slug, on pull.

gigadrive env pull

Pulled 7 environment variable(s) to .env.local.
Skipped 2 sensitive variable(s); secrets live only in production/preview environments.
Added .env.local to .gitignore.

The API resolves organization variables, then application variables, then the overrides for --environment when you pass one, and returns the non-sensitive result. Sensitive values are counted and never sent. The file is written with mode 0600, and its name is appended to .gitignore in the current directory. An existing target file raises an overwrite prompt that defaults to No, which --yes skips.

Credentials for a local app

--with-credentials provisions an application-scoped API key:

gigadrive env pull --with-credentials

Three entries land in the file, after the pulled variables:

GIGADRIVE_CLIENT_ID=0195c33e-0000-7000-8000-0000000000aa
GIGADRIVE_CLIENT_SECRET=gdnet_secret_...
GIGADRIVE_API_BASE_URL=https://api.gigadrive.network

The SDK reads those three by itself, so a process started from that file authenticates as the application with no further wiring. The key is created with the single scope network:env_vars:read and the API's default 90 day expiry. That scope set is fixed at creation, so a local app that does more than read variables needs a key you create yourself, covered in API keys.

GIGADRIVE_CLIENT_ID is the API key's ID, which doubles as the OAuth client ID. The secret is returned once at creation and cannot be read back, so the CLI records only the key ID, in ~/.gigadrive/dev-keys.json.

Reuse and rotation

On a later run the CLI reuses the credentials already in the file when all four of these hold:

you did not pass --rotate
the file contains both GIGADRIVE_CLIENT_ID and GIGADRIVE_CLIENT_SECRET
dev-keys.json has an entry for this application
that entry's key ID equals the file's GIGADRIVE_CLIENT_ID

Otherwise the CLI revokes the key it previously provisioned, mints a fresh one, and records the new ID. --rotate forces that path:

gigadrive env pull --with-credentials --rotate --yes

Rotation reaches only the key this CLI created for this application on this machine. Keys you created in the console are untouched, and a key that was already deleted server-side does not stop the run. Declining the overwrite prompt aborts before anything is minted or revoked.

Deployed code needs none of this. The platform injects a per-deployment identity under those same two variable names, so there is no long-lived secret for you to place or rotate in production. OIDC federation covers that path.

Do not export the generated file into your shell

The CLI reads GIGADRIVE_CLIENT_ID and GIGADRIVE_CLIENT_SECRET as its own non-interactive credentials. If either is set in the environment, gigadrive authenticates as the application and ignores your stored login, so commands outside network:env_vars:read start failing.