Commands

Help

devgrid-cli help

Prints usage information and available commands.

Authentication

Most commands that call the DevGrid API require authentication. The CLI resolves credentials in this order:

Access token — DEVGRID_ACCESS_TOKEN or --token
One-shot OAuth — username/password or client ID/secret via env vars or flags
Cached login — token from a previous devgrid login
Deprecated API key — DEVGRID_API_KEY (fallback only; a deprecation warning is shown)

`devgrid login`

Cache OAuth credentials for local use.

devgrid-cli login [options]

Flag	Description
`--username`	Username for password grant
`--password`	Password (prompted if omitted with `--username`)
`--client-id`	Client ID for client credentials grant
`--client-secret`	Client secret (prompted if omitted with `--client-id`)
`--env`	Environment for credential storage (`prod`, `dev`, `local`; default from `ENV`)

Password grant (interactive):

devgrid-cli login --username [email protected]

Client credentials grant (automation-friendly):

devgrid-cli login --client-id YOUR_CLIENT_ID --client-secret YOUR_SECRET

Credentials are stored at ~/.config/devgrid/<env>/credentials.json (or $XDG_CONFIG_HOME/devgrid/<env>/credentials.json).

Note: SSO users cannot use the password grant with their SSO password. Use a dedicated service account or client credentials grant. Confirm client credentials availability with your DevGrid administrator.

`devgrid logout`

Remove cached credentials for an environment.

devgrid-cli logout [--env prod]

`devgrid auth status`

Show whether you are logged in, the grant type, and token expiry.

devgrid-cli auth status [--env prod]

Example output when logged in:

Logged in to prod (password grant)
Token expires: 2026-07-01T15:30:00Z

Auth environment variables

Variable	Purpose
`DEVGRID_ACCESS_TOKEN`	Pre-fetched OAuth access token (highest priority)
`DEVGRID_USERNAME`	Username for one-shot password grant
`DEVGRID_PASSWORD`	Password for one-shot password grant
`DEVGRID_CLIENT_ID`	Client ID for one-shot client credentials grant
`DEVGRID_CLIENT_SECRET`	Client secret for one-shot client credentials grant
`DEVGRID_API_KEY`	Deprecated — legacy API key fallback
`DEVGRID_AUTH_URL`	Override OAuth token endpoint
`DEVGRID_AUDIENCE`	OAuth audience (default: `https://api.devgrid.io`)
`DEVGRID_ENV`	API environment selector (`dev` or `prod`)
`ENV`	Config section / credential store environment (`local`, `dev`, `prod`)

CI examples

Client credentials (recommended for pipelines):

# GitHub Actions example
env:
  DEVGRID_CLIENT_ID: ${{ secrets.DEVGRID_CLIENT_ID }}
  DEVGRID_CLIENT_SECRET: ${{ secrets.DEVGRID_CLIENT_SECRET }}
steps:
  - run: devgrid-cli sync

Confirm that client credentials are enabled for your DevGrid tenant before relying on this in production CI.

Pre-fetched access token:

export DEVGRID_ACCESS_TOKEN="${{ secrets.DEVGRID_ACCESS_TOKEN }}"
devgrid-cli sync

Legacy API key (deprecated):

export DEVGRID_API_KEY=your-api-key
devgrid-cli sync

Init

Create a starter devgrid.yml in the current directory.

devgrid-cli init

If devgrid.yml already exists, the command exits without overwriting.

Lint

Validate devgrid.yml against the CLI schema.

devgrid-cli lint

Checks that required fields are present, types are correct, and no unsupported properties are included. Run this before sync in CI.

Minimal example:

project:
  appId: my-app
  components:
    - name: my-service
      shortId: svc-001

For the full schema, field reference, and examples, see devgrid.yml.

Sync

Apply local devgrid.yml configuration to DevGrid.

devgrid-cli sync [options]

Requires authentication — see Authentication above.

Flag	Description
`--repo-id`	Link synced components to a repository ID in DevGrid
`--token`	OAuth access token (overrides env)
`--username`	One-shot password grant username
`--password`	One-shot password grant password
`--client-id`	One-shot client credentials client ID
`--client-secret`	One-shot client credentials client secret

The sync process:

Validates devgrid.yml
Fetches current state from DevGrid
Creates or updates applications and components
Establishes relationships and dependencies
Optionally links components to a repository when --repo-id is set

Dry Run

Preview sync changes without applying them.

devgrid-cli dry_run [options]

Accepts the same authentication and sync flags as devgrid sync.

Output is controlled by configuration.dryRunOutput in devgrid.yml:

Value	Behavior
`file` (default)	Writes plan to `devgrid_dry_run_plan.json`
`stdout`	Prints the plan to standard output

Example plan file contents include proposed CREATE, UPDATE, DELETE, and WARN actions for each resource.

Event

Send a deployment or build event to DevGrid.

devgrid-cli event [options]