CLI Reference

The GGNomad CLI (ggnomad from @ggnomad/cli) is a thin shell over @burdenoff/cli-sdk. It mounts the GGNomad product context and exposes all shared platform modules plus the GGNomad domain surface.

Install

npm install -g @ggnomad/cli
# or
bun add -g @ggnomad/cli

Environment selection

The CLI defaults to production endpoints. Set BURDENOFF_ENV to target alpha or local before running any command:

BURDENOFF_ENV	Workspace gateway	Global gateway	OIDC issuer
prod (default)	https://graphqlworkspaces.burdenoff.com/workspaces/graphql	https://graphql.burdenoff.com/global/graphql	https://graphql.burdenoff.com/global
alpha	https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql	https://alphagraphql.burdenoff.com/global/graphql	https://alphagraphql.burdenoff.com/global
local	http://localhost:4003/workspaces/graphql	http://localhost:4000/global/graphql	http://localhost:4000/global

You can also override per command via env vars:

export GGNOMAD_WORKSPACE_ENDPOINT="https://graphqlworkspaces.burdenoff.com/workspaces/graphql"
export GGNOMAD_GLOBAL_ENDPOINT="https://graphql.burdenoff.com/global/graphql"
export GGNOMAD_OIDC_ISSUER="https://graphql.burdenoff.com/global"

Authentication

All workspace operations require dual-token auth (platform token + workspace token). The workspace token is issued automatically when you set a workspace.

User Authentication (OAuth2 Device Code)

Interactive browser-based login.

# Login — opens browser for approval
ggnomad auth login

Common Auth Commands

ggnomad auth status                # Check current auth state
ggnomad auth token                 # Print platform access token
ggnomad auth token --workspace     # Print workspace token
ggnomad auth refresh               # Force token refresh
ggnomad auth logout                # Clear stored tokens

ggnomad workspace list             # List available workspaces
ggnomad workspace current          # Show current workspace
ggnomad workspace set <id>         # Switch workspace (re-issues token)

Token storage: ~/.config/ggnomad-cli/auth.json (mode 0600).

Command groups

ggnomad auth            Authentication (login, logout, status, token, refresh)
ggnomad workspace       Workspace context (list, current, set)
ggnomad organizations   Organization management
ggnomad tours           Product tours
ggnomad rbac            Role-based access control
ggnomad ggnomad         GGNomad marketplace (providers, properties,
                          activities, events, tours, trips, bookings,
                          favorites, analytics)
ggnomad sandbox         Sandbox script execution
ggnomad tags            Tags
ggnomad files           Files
ggnomad groups          Groups
ggnomad conversations   Conversations
ggnomad security        Security
ggnomad integrations    Integrations
ggnomad channels        Channels
ggnomad scheduler       Scheduler
ggnomad export          Data export
ggnomad notifications   Notifications
ggnomad support         Support
ggnomad products        Products / feature flags
ggnomad billing         Billing
ggnomad store           Store
ggnomad devportal       Developer portal
ggnomad health          Health checks

Run ggnomad <command> --help for subcommand details.

Quick Examples

ggnomad auth login
ggnomad workspace set <id>
ggnomad ggnomad properties list
ggnomad ggnomad providers list
ggnomad tags create --key bug --label Bug
ggnomad rbac check <user> read project
ggnomad billing subscriptions list
ggnomad devportal apps list --status PUBLISHED

Output Formats

All list/get commands support --format (-f): json, table, yaml.

Development

Prerequisites

• Bun 1.3.14+
• Node.js 24.11.0+
• TypeScript 5.9+

Setup

git clone https://github.com/Algoshred/ggnomad-cli.git
cd ggnomad-cli
bun install

Commands

bun run dev              # Run CLI in dev mode (tsx)
bun run dev -- --help    # Dev mode with args
bun run build            # Compile TypeScript (tsc + tsc-alias)
bun run type-check       # Type checking
bun run lint             # ESLint
bun run format           # Prettier
bun run sanity           # All checks (format + lint + type-check + build)
bun run start            # Run compiled CLI

Project Structure

src/
  cli.ts                 # Entry point — builds CLIContext, mounts SDK modules, runs program
  product-defaults.ts    # GGNomad endpoints, OIDC client id, env prefix

All command logic lives in @burdenoff/cli-sdk modules.

CI/CD

Every push to main / PRs (CI): Lint → Type check → Build → CLI smoke (--help, --version). No publish — the gate is green-only.

Release (manual workflow_dispatch or CalVer git tag): Lint → Type check → Build → Publish to npmjs (public) → GitHub Release.

CalVer format: YYYY.MDD.PATCH (e.g., 2026.626.1).

Links

• npm: @ggnomad/cli
• Source: github.com/Algoshred/ggnomad-cli
• Issues: github.com/Algoshred/ggnomad-cli/issues