GebSecure CLI

gebsecure manages AI-agent security from the terminal and from CI: policy-as-code (validate, format, test, diff, deploy, roll back), agents and their credentials, vault secrets, integrations, policy simulation and the audit log. It is built on the official TypeScript SDK (@gebsecure01/sdk) and bundles the same GSL parser, validator, formatter and evaluation engine the server uses, so policies validate, fmt, test and simulate --local work offline.

The complete list of commands and flags is in the generated command reference.

• Install
• Quick start
• Authentication
• CI authentication
• Configuration and profiles
• Policy-as-code
• Simulation
• Agents, secrets, integrations, logs
• Output, errors and exit codes
• Shell completion
• Security notes
• Development and releases

Install

npm install -g @gebsecure01/cli      # Node.js 20+
gebsecure --version

Or run it without installing: npx @gebsecure01/cli <command>.

Standalone executables that do not need Node.js are attached to each release of github.com/gebsecure/gebsecure-cli for Linux (x64, arm64), macOS (x64, arm64) and Windows (x64), together with a single-file bundle (gebsecure.mjs) and SHA256SUMS:

curl -fsSLO https://github.com/gebsecure/gebsecure-cli/releases/download/v0.1.1/gebsecure-linux-x64
curl -fsSLO https://github.com/gebsecure/gebsecure-cli/releases/download/v0.1.1/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
install -m 0755 gebsecure-linux-x64 /usr/local/bin/gebsecure

From a checkout of this repository: npm ci && npm run build -w @gebsecure01/cli && node cli/dist/gebsecure.mjs --help.

Quick start

gebsecure login                     # email + password (hidden), pick an organization
cd my-repo
gebsecure init                      # gebsecure.yaml + policies/ with a starter policy and tests
gebsecure policies validate         # offline
gebsecure policies test             # offline, same engine as the server
gebsecure deploy                    # plan → confirm → deploy to the configured environment
gebsecure simulate simulations/     # decisions for scenario files, against what is deployed
gebsecure logs --since 1h -f        # follow the audit log

Authentication

gebsecure login signs in with email and password. The password is read without echo from the terminal, or non-interactively with --password-stdin (or GEBSECURE_PASSWORD). If you belong to several organizations, choose one with --org <id|slug> or from the interactive list.

gebsecure login --email [email protected] --org acme
printf '%s' "$PASSWORD" | gebsecure login --email [email protected] --password-stdin

The session is stored for the active profile in credentials.json in the configuration directory:

| Platform | Directory | Protection | | --- | --- | --- | | Linux, macOS | $XDG_CONFIG_HOME/gebsecure or ~/.config/gebsecure | directory 0700, files 0600 | | Windows | %APPDATA%\gebsecure | ACL replaced with a single full-control entry for the current user (inheritance removed) |

GEBSECURE_CONFIG_DIR overrides the location. Access tokens are short-lived and are refreshed automatically with the single-use refresh token (rotated on every refresh, under a file lock so parallel CLI processes never replay a token). gebsecure logout revokes the session on the server and deletes the local credentials. Tokens, passwords and secrets are never printed.

You can also store a non-interactive credential in a profile:

printf '%s' "$KEY" | gebsecure login --with-api-key --profile ci
printf '%s' "$SECRET" | gebsecure login --with-client-credentials --client-id cred_… --profile ci

gebsecure whoami shows the principal, organization, role and the credential source in use.

CI authentication

In CI no login is needed; set one of these environment variables (first match wins):

| Variable | Credential | | --- | --- | | GEBSECURE_API_KEY | API key (gsk_…) | | GEBSECURE_CLIENT_SECRET (+ optional GEBSECURE_CLIENT_ID, GEBSECURE_SCOPE) | client credentials of a service account or agent, exchanged for short-lived tokens by the SDK | | GEBSECURE_TOKEN | a pre-obtained access token |

They take precedence over anything stored in a profile. Destructive commands require --yes when stdin is not a terminal. A complete GitHub Actions workflow (checks on pull requests, deploy on merge) is in docs/cli/github-actions.md.

Configuration and profiles

Settings: api-url, gateway-url, org, project, environment (ids or slugs) and output. They come from, highest precedence first:

1. command-line flags (--api-url, --org, --project, --env, --output, --profile)
2. environment variables (GEBSECURE_API_URL, GEBSECURE_ORG, GEBSECURE_PROJECT, GEBSECURE_ENVIRONMENT, GEBSECURE_OUTPUT, GEBSECURE_PROFILE)
3. the project file gebsecure.yaml (nearest one in the current or a parent directory)
4. the active profile (config.json in the configuration directory)
5. built-in defaults (https://api.gebsecure.com, table)

gebsecure config set api-url https://api.gebsecure.example.com
gebsecure config use staging                 # create/switch the default profile
gebsecure --profile staging config set environment staging
gebsecure config list                        # effective values and where each comes from
gebsecure config profiles

Project file: gebsecure.yaml

gebsecure init creates gebsecure.yaml at the repository root (a single file, so it is visible in code review and easy to find; a hidden .gebsecure/ directory is already used by the server for local development keys). Commit it.

version: 1
org: "acme"
project: "payments"
environment: "staging"
policies:
  dir: "policies"        # one <name>.gsl per policy, optional <name>.test.yaml
  scope: environment     # scope of policies created by deploy: org | project | environment

Policy-as-code

policies/
  agent-baseline.gsl          # the policy named "agent-baseline" (one or more `policy "…" { }` rules)
  agent-baseline.test.yaml    # its tests
simulations/
  smoke.yaml                  # scenarios for `gebsecure simulate`

Tests are requests with the expected decision:

tests:
  - name: larger refunds need approval
    request:
      principal: { type: agent, id: agt_example }
      action: stripe:refunds.create
      resource: stripe:charge/ch_123
      context: { amount: 500 }
    expect: APPROVAL_REQUIRED      # ALLOW | DENY | APPROVAL_REQUIRED

| Command | What it does | | --- | --- | | policies validate [--remote] | Syntax, semantic checks and conflict analysis across the directory (offline); --remote also asks the API | | policies fmt [--check] | Canonical formatting (files with comments are skipped unless --force, because formatting drops comments) | | policies test [--remote] | Runs every test against the whole local policy set; --remote runs the server-stored tests against the environment's effective set | | policies diff / policies plan | Local files vs the server (exit 7 when they differ) | | deploy (= policies deploy) | Local gate (validation + tests), plan with diffs, confirmation (--yes in CI), then create/update versions, sync tests and deploy | | policies versions, policies get, policies rollback | History, source of any version, roll back to the previous or a given version |

The server re-runs the tests and conflict analysis against the environment's effective policy set (org- and project-level policies, RBAC grants) when deploying and blocks a failing deployment; the CLI then reports the failing tests and exits with code 7.

Simulation

gebsecure simulate simulations/                      # against the deployed policies (server)
gebsecure simulate refunds.yaml --candidate          # local policy files as candidates vs deployed
gebsecure simulate refunds.yaml --candidate --fail-on-change
gebsecure simulate simulations/ --local              # fully offline

A scenario file is { environment?, requests: [...] } (or just a list of requests); each request is a test request plus optional label and expect. The output shows the decision, the risk input of the request and the matched policies; any expect mismatch exits with code 7.

Agents, secrets, integrations, logs

gebsecure agents create billing-bot --risk-tier elevated --credential-file ./billing-bot.json
gebsecure agents rotate billing-bot --grace-minutes 30 --credential-file ./billing-bot.json
gebsecure agents suspend billing-bot --reason "incident 42"
gebsecure agents revoke billing-bot --all --yes

gebsecure secrets create stripe-key --type api_key --from-file ./stripe.key
printf '%s' "$TOKEN" | gebsecure secrets create github-token --type oauth_token
gebsecure secrets rotate stripe-key            # prompts for the new value without echo
gebsecure secrets revoke stripe-key --version 1 --yes

gebsecure integrations catalog
gebsecure integrations create crm --connector rest --auth-type oauth2 --config @crm.json
gebsecure integrations oauth crm --client-id my-client --client-secret-stdin < client-secret.txt
gebsecure integrations test crm

gebsecure logs --since 24h --decision DENY
gebsecure logs --agent agt_… -f -o ndjson
gebsecure logs export --since 7d --format csv --out audit.csv

A new agent credential is shown exactly once — or written with owner-only permissions to --credential-file. Secret values are read from stdin, --from-file or a hidden prompt; passing one on the command line (--value, hidden from help) works but prints a warning. The vault is write-only: secrets list/get show metadata and masks only.

integrations oauth starts a loopback listener on 127.0.0.1 (--port to match the redirect URI registered with the provider), prints/opens the authorization URL and completes the installation; the tokens go straight into the vault. With --redirect-uri you paste the final URL instead.

Output, errors and exit codes

-o table (default), -o json, -o yaml or -o ndjson. Results go to stdout; progress, warnings and errors go to stderr, so -o json output can be piped. --quiet suppresses informational messages and makes lists print IDs only. Colour is disabled with --no-color, NO_COLOR, or when stdout is not a terminal.

API errors show the problem title, detail, validation details and the request id:

Error: validation_failed (HTTP 422): Policy is invalid
  error: Expected "permit" or "forbid" (line 2:10)
Request ID: 8f0c1e3b-…

Stack traces are shown only with --debug (which also logs each HTTP request) and are redacted.

| Code | Meaning | | --- | --- | | 0 | success | | 1 | general error | | 2 | usage error | | 3 | not authenticated | | 4 | permission denied | | 5 | not found | | 6 | validation failed | | 7 | check failed (tests, simulation expectations, diff/fmt --check, deployment blocked) | | 8 | conflict | | 9 | unavailable / network / rate limited | | 130 | interrupted |

Shell completion

gebsecure completion bash > ~/.local/share/bash-completion/completions/gebsecure
gebsecure completion zsh > "${fpath[1]}/_gebsecure"
gebsecure completion fish > ~/.config/fish/completions/gebsecure.fish
gebsecure completion powershell | Out-String | Invoke-Expression   # add to $PROFILE

Scripts are generated from the command definitions and complete commands, subcommands, flags and flag values (e.g. --output, --risk-tier), and file paths where a flag takes a file.

Security notes

• Credentials live only in credentials.json (owner-only); config.json holds no secrets. The CLI warns if credentials.json becomes readable by others.
• Everything the CLI prints passes through redaction (GebSecure token formats, JWTs, password=-style values and any secret read during the run). The only exception is a new agent client secret, which is shown once by design (use --credential-file to keep it off the terminal).
• A profile is bound to the API URL it logged in to; using it against another URL is refused.
• Plain-HTTP API URLs are accepted for local development; config set warns for non-local hosts.

Development and releases

npm run dev -w @gebsecure01/cli -- --help      # run from source (tsx)
npm run typecheck -w @gebsecure01/cli
npm run test -w @gebsecure01/cli               # unit tests
GEBSECURE_CLI_E2E=1 npm run test:e2e -w @gebsecure01/cli   # live: real API, gateway and worker, PostgreSQL + Redis
npm run docs -w @gebsecure01/cli               # regenerate docs/cli/reference.md (CI runs docs:check)
npm run build -w @gebsecure01/cli              # dist/gebsecure.mjs (single-file ESM bundle)
npm run build:sea -w @gebsecure01/cli          # dist/sea/gebsecure-<platform>-<arch>[.exe] for this platform

The live end-to-end suite uses its own database (gebsecure_test_cli, reset on each run), Redis DB 12 and ports 18601–18607.

Releases: push a cli-v<version> tag matching cli/package.json and src/version.ts. The cli workflow runs the tests (unit on Linux/macOS/Windows, live e2e), builds standalone executables on each platform, publishes @gebsecure01/cli to npm with trusted publishing (OIDC, npm environment) and creates release v<version> in the public gebsecure/gebsecure-cli repository with the binaries and SHA256SUMS (CLI_RELEASE_TOKEN, a fine-grained token limited to that repository, in the cli-release environment). The Windows and macOS executables are not code-signed yet.