@gabaltech/cli

Command-line interface for the Gabaltech Internal Developer Platform. Trigger deployments, manage users, provision services from blueprints, and generate Terraform from designs or plain-text prompts.

npm install -g @gabaltech/cli

Requires Node.js 18 or later.

Quick start

1. Get an API key

Open https://forge.gabaltech.co.uk/admin/api-keys, create a key with the cli scope, and copy it.

2. Authenticate

gabal login --token <your-api-key>

3. Deploy a service

gabal deploy trigger website dev --version 1.4.2 --reason "fix login bug"

Authentication

Every command talks to the IDP over HTTPS using a Bearer token. The API key is read from, in order of priority:

1. GABALTECH_API_KEY environment variable
2. api-key key in ~/.gabaltech/config.json

To store the key for all future commands:

gabal login --token <your-api-key>

Configuration

Config is stored in ~/.gabaltech/config.json. All settings can be overridden by environment variables.

| Config key | Environment variable | Default | Description | |-------------------|----------------------------|---------------------------------|------------------------------| | api-key | GABALTECH_API_KEY | — | API key for authentication | | forge-url | GABALTECH_FORGE_URL | https://forge.gabaltech.co.uk | Forge base URL | | aws-profile | AWS_PROFILE | gabaltech | AWS CLI profile | | cognito-pool-id | COGNITO_USER_POOL_ID | — | Cognito user pool ID |

Manage config directly with the config command:

gabal config set forge-url https://forge.staging.gabaltech.co.uk
gabal config get forge-url
gabal config unset forge-url
gabal config list

config list masks the api-key value (shows first 12 characters only).

Commands

gabal login

Authenticate with the IDP.

gabal login --token <api-key>
gabal login --token <api-key> --url https://idp.staging.gabaltech.co.uk

Without --token, prints instructions for creating a key in the IDP web UI.

| Flag | Description | |------|-------------| | --token <api-key> | API key to save | | --url <url> | Override IDP base URL |

gabal config

Read and write CLI configuration.

gabal config set <key> <value>
gabal config get <key>
gabal config unset <key>
gabal config list

gabal deploy

Trigger and inspect deployments.

deploy trigger <service> <environment>

Queue a deployment. For dev and test environments the pipeline starts immediately. For prod the request enters an approval queue.

gabal deploy trigger website dev
gabal deploy trigger website prod --version 2.0.1 --reason "release 2.0"

| Flag | Default | Description | |------|---------|-------------| | --version <tag> | latest | Image tag or version to deploy | | --reason <text> | CLI trigger | Reason recorded on the deployment |

Output: Deployment queued: <id> [<status>]

deploy list

List recent deployments.

gabal deploy list
gabal deploy list --service website --env prod --limit 10
gabal deploy list --json

| Flag | Default | Description | |------|---------|-------------| | --service <name> | — | Filter by service name | | --env <env> | — | Filter by environment | | --limit <n> | 20 | Maximum number of results | | --json | — | Output raw JSON |

gabal blueprints

List available service blueprints and provision new services from them.

blueprints list

gabal blueprints list
gabal blueprints list --json

| Flag | Description | |------|-------------| | --json | Output raw JSON |

blueprints provision <catalogId> <serviceName> <environment>

Provision a new service from a blueprint catalog entry.

gabal blueprints provision dynamodb my-table dev
gabal blueprints provision dynamodb my-table dev --field billingMode=PAY_PER_REQUEST --field pointInTimeRecovery=true

| Flag | Description | |------|-------------| | --field <key=value> | Blueprint field value (repeatable) | | --json | Output raw JSON |

gabal users

Manage IDP users (backed by AWS Cognito). Requires an API key with admin scope.

users list

gabal users list
gabal users list --json

users invite <email>

Invite a new user. The IDP sends them a temporary password.

gabal users invite [email protected] --name "Alice Smith"
gabal users invite [email protected] --name "Bob Jones" --admin

| Flag | Description | |------|-------------| | --name <name> | Display name | | --admin | Grant the approver role on invite |

users delete <username>

gabal users delete [email protected]

users set-admin <username>

Grant or revoke the approver role.

gabal users set-admin [email protected]
gabal users set-admin [email protected] --revoke

| Flag | Description | |------|-------------| | --revoke | Remove the admin role instead of granting it |

users sync --file <path>

Bulk-create or update users from a YAML or JSON file. Existing users are updated; new users are invited.

gabal users sync --file users.yaml
gabal users sync --file users.json --dry-run
gabal users sync --file users.yaml --json

| Flag | Description | |------|-------------| | --file <path> | Path to a YAML or JSON users file (required) | | --dry-run | Print what would happen without making any changes | | --json | Output raw JSON result |

File format (YAML example):

users:
  - email: [email protected]
    is_admin: true
  - email: [email protected]

The top-level value may be an array directly ([{email: ...}, ...]) or an object with a users array.

gabal api-keys

Manage IDP API keys. Requires an API key with admin scope.

api-keys list

gabal api-keys list
gabal api-keys list --json

Key hashes are never returned by the API. The list shows IDs, names, scopes, creator, and last-used timestamp.

api-keys create <name>

gabal api-keys create my-ci-key
gabal api-keys create deploy-bot --scope deployments --scope catalogs

The full API key is printed once on creation and never retrievable again. Save it immediately.

| Flag | Default | Description | |------|---------|-------------| | --scope <scope> | admin | Scope to grant (repeatable) |

After creation, store locally:

gabal config set api-key <the-key-shown>

api-keys revoke <keyId>

gabal api-keys revoke a1b2c3d4

The keyId is the first 8 characters shown in api-keys list or the full ID from api-keys create.

gabal generate

Generate Terraform from an IDP design or a plain-text architecture prompt. Requires an API key.

gabal generate --design d-abc123
gabal generate --prompt "S3 bucket with versioning, lifecycle rule after 30 days to Glacier"
gabal generate --prompt "ECS Fargate service, ALB, ACM cert, Route53 A record" --output ./infra

| Flag | Default | Description | |------|---------|-------------| | --design <designId> | — | Design ID from the IDP | | --prompt <text> | — | Plain-text architecture description | | --output <dir> | ./gabaltech-infra | Directory to write files into |

Exactly one of --design or --prompt is required.

Output files written to <dir>/:

| File | Contents | |------|----------| | main.tf | Main resource definitions | | variables.tf | Input variable declarations | | outputs.tf | Output value declarations |

gabal review

AI-powered review of Terraform files. Findings are sorted by severity: CRITICAL first, then WARNING, then INFO.

gabal review --file main.tf
gabal review --dir ./infra

| Flag | Description | |------|-------------| | --file <path> | Single .tf file to review | | --dir <path> | Directory — all .tf files are concatenated and reviewed together |

Exactly one of --file or --dir is required.

gabal docs

Generate architecture documentation from an IDP design.

gabal docs --design d-abc123
gabal docs --design d-abc123 --output ./docs

| Flag | Default | Description | |------|---------|-------------| | --design <designId> | — | Design ID from the IDP (required) | | --output <dir> | ./gabaltech-docs | Directory to write files into |

Output files written to <dir>/:

| File | Contents | |------|----------| | architecture.md | Architecture overview | | runbook.md | Operational runbook |

gabal init

Scaffold a new Gabaltech project directory.

gabal init
gabal init --name payments-service --type serverless

| Flag | Default | Description | |------|---------|-------------| | --name <project> | my-project | Project name (used as directory name) | | --type <type> | container | Project type: serverless, container, or platform |

Creates:

<name>/
├── infra/
├── docs/
└── gabaltech.json

gabaltech.json records the project name, type, and IDP URL.

Tracking registers

Sixteen operational registers, each real and DynamoDB-backed on Forge (previously writable only through Forge's own web UI -- create was added to the CLI on 2026-08-10 so CI/automation can populate them too). Every one follows the same shape: list with --json, and create with the required fields as positional args and the rest as flags. Every create prints Created: <id> (or --json for the raw { id }).

| Command | Create | Notes | |---------|--------|-------| | gabal okr | create <team> <quarter> <title> | --key-result <text> repeatable, --status, --description | | gabal adr | create <service> <title> | --context, --decision, --consequences, --status, --deciders | | gabal tech-debt | create <service> <title> | --severity, --category, --effort, --owner, --description | | gabal chaos | create <service> <title> <hypothesis> <method> | method: cpu-stress/network-latency/packet-loss/pod-kill/disk-fill/custom; --scheduled-at | | gabal retro | create <team> | --went-well/--to-improve/--action <text> each repeatable; --sprint, --date | | gabal handover | create <team> <shift> <handoverTo> | --incidents, --watchlist, --notes | | gabal roadmap | create <quarter> <year> <title> | --team, --status, --priority, --github-issue | | gabal rate-limits | create <service> <endpoint> | --per-minute, --per-hour, --burst, --status, --notes | | gabal release-train | create <name> | --environment <env> repeatable, --service <name[:version]> repeatable, --target-date, --conductor | | gabal blue-green | create <service> | --blue-version, --green-version, --active-slot (default blue), --notes | | gabal pipeline-failures | create <service> | --pipeline-id, --branch, --stage, --error-message, --category | | gabal cost-per-service | create <service> <period> <year> <month> | --compute, --storage, --network, --other, --currency (default GBP) | | gabal tenant-config | create <tenant> <key> <value> | --value-type, --description, --environment (default all) | | gabal cve-register | create <service> <dependency> <cveId> | --severity, --version, --affected-versions, --fixed-version, --status | | gabal dr-readiness | create <service> | --backup-enabled, --backup-frequency, --rto, --rpo, --tier, --owner | | gabal license-register | create <service> <dependency> <license> | --approved, --risk, --version, --reviewed-by |

gabal okr create platform Q1-2026 "Ship the Nexus visibility panel" --key-result "Wire Forge summary API" --status on-track
gabal chaos create forge "Kill a pod" "Service recovers within 30s" pod-kill
gabal release-train create v2.0 --environment dev --environment test --service forge:2.0.1 --service nexus
gabal tenant-config create acme maxSeats 50

Each list supports its own filter flags (--service, --team, --status, etc.) -- run gabal <command> list --help for the exact set per domain.

CI/CD usage

Set GABALTECH_API_KEY as a CI secret rather than committing a config file.

# GitLab CI / GitHub Actions example
GABALTECH_API_KEY=$GABALTECH_API_KEY gabal deploy trigger website prod --version $CI_COMMIT_TAG

Override the IDP URL for staging pipelines:

GABALTECH_FORGE_URL=https://forge.staging.gabaltech.co.uk gabal deploy trigger website test

License

UNLICENSED — internal use only.