CLI Reference
Complete reference for every gibson command, flag, and default, generated from the CLI.
gibson is the local command-line interface for the Gibson platform. This page lists every command exhaustively; the guides walk you through the common workflows.
gibson — tooling for the Gibson agent / tool / plugin
development lifecycle.
Subcommands:
login authenticate the CLI against the platform (device flow)
logout end the CLI session and remove stored credentials
init initialize a Gibson workspace (.gibson/workspace.yaml)
component scaffold, validate, build, run components (agent | tool | plugin)
connector enable and manage tenant connectors (catalog | enable | list | disable)
docs emit machine-readable docs (JSON Schemas, etc.)
inspect show what this principal can do (calls WhoAmI)
mission author, validate, render, submit gibson missions
target create, list, inspect, update, delete assessment targets
agent manage agent/tool/plugin machine identities
Global flags
Available on every command.
| Flag | Type | Default | Description |
|---|---|---|---|
--ca-cert | string | — | PEM file with a CA certificate to trust IN ADDITION to the system store (env: GIBSON_CA_CERT) |
Commands
gibson agent
Manage agent/tool/plugin machine identities (AgentIdentityService)
gibson agent — provision and manage machine identities for
agents, tools, and plugins via AgentIdentityService on the Gibson
daemon. Authenticated as you: run `gibson login` first.
Subcommands:
enroll provision a new machine identity and print the one-time secret
list list all identities for the tenant
revoke permanently revoke an identity by principal ID
gibson agent enroll
Provision a new machine identity and print the one-time bootstrap token
Call AgentIdentityService.CreateAgentIdentity to provision a new
machine identity, authenticated as you (run `gibson login` first).
The one-time bootstrap token is printed to stdout — store it immediately;
it cannot be retrieved again. Pass it to the component as
GIBSON_BOOTSTRAP_TOKEN and start the binary once: it completes the
capability-grant handshake itself (ADR-0045, sdk#128). The same flow serves
every component kind.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--capability | stringArray | — | Session capability to grant in the credential ceiling; repeatable. Reserved names: mission:originate (start its own mission), mission:delegate |
--description | string | — | Human-readable description |
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--kind | string | agent | Component kind: agent | tool | plugin |
--name | string | — | Identity name (required) |
--timeout | duration | 30s | RPC deadline |
gibson agent list
List all machine identities for the tenant
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--kind | string | — | Filter by kind: agent | tool | plugin (default: all) |
--timeout | duration | 30s | RPC deadline |
gibson agent revoke
Permanently revoke a machine identity
Call AgentIdentityService.RevokeAgentIdentity. The identity is
immediately invalidated; existing JWTs for the principal stop being
accepted by the daemon. This action is irreversible.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | RPC deadline |
gibson component
Scaffold, validate, build, and run Gibson components (agent | tool | plugin | connector)
component — kind-aware tooling for the Gibson developer workflow.
Subcommands:
init scaffold a new component directory from templates
generate regenerate gen/ from taxonomy.yaml and ontology.yaml
build generate + validate + go build (one-step developer loop)
validate local schema + proto checks against a component directory
run run the compiled component binary, supervising its signals
--kind is required on validate and run. It used to be auto-detected from
component.yaml, which no longer exists (ADR-0097): everything else about a
component is implied by its directory, and the kind is not.
A component enrols itself at boot from GIBSON_URL and
GIBSON_BOOTSTRAP_TOKEN (sdk#128), so there is no register verb.
gibson component build
Generate, validate, and compile the component binary
build is the one-step developer loop command:
1. generate — regenerate gen/ from taxonomy.yaml + ontology.yaml
2. validate — run all local checks (main.go parses, proto field 100,
buf lint, ontology YAML parse)
3. proto — run buf generate when buf.gen.yaml exists and api/gen
is missing or older than api/proto (needs buf,
protoc-gen-go and protoc-gen-go-grpc on PATH)
4. mod tidy — populate go.sum on a freshly scaffolded component
(skipped once go.sum exists)
5. go build — compile the component binary into the component directory
build delegates to the generate and validate subcommands, resolves
modules when go.sum is absent, then runs `go build ./...` in the
component directory. Use `gibson component generate`
or `gibson component validate` individually if you want finer control.
Exit codes:
0 build succeeded
1 generate / validate / compile error (details on stderr)
--kind is required, because step 2 is kind-aware and the kind used to come
from component.yaml, which no longer exists (ADR-0097).
Examples:
gibson component build --kind tool
gibson component build --kind plugin --dir ./my-plugin
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
-d, --dir | string | . | component directory |
--kind | string | — | component kind: agent | tool | plugin (required) |
gibson component generate
Generate Go bindings from taxonomy.yaml and ontology.yaml
generate reads taxonomy.yaml and ontology.yaml (if present) in the
component directory and emits Go source files under gen/:
gen/ontology_extension.go — exports OntologyExtension() returning a
graphrag.OntologyExtension populated from
the parsed ontology.yaml
Generated files are byte-stable across runs: map keys are sorted and
go/format is applied. Commit the gen/ directory; diffs reflect only
intentional ontology changes.
generate is a no-op if neither YAML file is present (it prints a notice
and exits 0 rather than failing).
Examples:
gibson component generate
gibson component generate --dir ./my-tool
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
-d, --dir | string | . | component directory |
gibson component init
Scaffold a new component directory (agent | tool | plugin | connector)
init scaffolds a new Gibson component directory from embedded
templates. The kind selects which template set to render and what file
shape the new directory has:
agent: main.go (sdk.NewAgent + sdk.ServeAgent) +
go.mod + Makefile + Dockerfile + README + AGENTS.md +
CLAUDE.md + prompts/ + .claude/settings.json
tool: like agent, plus api/proto/gibson/tools/<pkg>/v1/<pkg>.proto
with field 100 = gibson.graphrag.v1.DiscoveryResult, buf.yaml,
buf.gen.yaml, and proto/vendor/ for the SDK protos
plugin: Go-first (ADR-0065 R4). handler.go declares the plugin in
code (plugin.Serve + WithName, WithVersion, WithHandler, typed
Go request/response structs — no .proto, no manifest file,
ADR-0097) + a hermetic handler_test.go with a
committed cassette under testdata/ + helm/values.yaml +
go.mod + Makefile + Dockerfile + README + AGENTS.md +
CLAUDE.md + prompts/ + .claude/settings.json
connector: Declarative (ADR-0065 R6). connector.yaml manifest (the
integration IS the manifest — no Go code) + a hermetic
schema-validation smoke test (connector_test.go) + go.mod +
README + AGENTS.md + CLAUDE.md + .claude/settings.json
The name must match ^[a-z][a-z0-9-]{0,61}[a-z0-9]$ (DNS-label style).
--with-secret is plugin-only. It names a broker secret that the plugin
resolves at start, so a missing grant fails the boot with the secret named.
A tenant admin grants the secret when the plugin is deployed.
Examples:
gibson component init my-agent --kind agent
gibson component init my-scanner --kind tool
gibson component init my-plugin --kind plugin --with-secret cred:api_key
gibson component init my-plugin --kind plugin --dir ~/projects --force
gibson component init gitlab --kind connector
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
-d, --dir | string | — | destination directory (default: current directory) |
--force | bool | — | overwrite existing files |
--kind | string | — | component kind: agent | tool | plugin | connector (required) |
--with-secret | stringArray | — | plugin-only: a broker secret the plugin resolves at start, e.g. cred:api_key (repeatable) |
gibson component run
Run the compiled component binary, supervising its signals
run starts the compiled component binary in this directory, forwards
its stdout/stderr to the operator's terminal, hooks SIGINT/SIGTERM, and
waits up to --drain-timeout (default 30s) for graceful shutdown before
escalating to SIGKILL.
run is a thin process supervisor — it does NOT compile the binary
(use `make build` first) and it does NOT mock handlers. The
component's existing graceful-drain logic in plugin.Serve / serve.Agent /
serve.Tool is the contract; this verb just supervises it.
--kind is required. It used to be auto-detected from component.yaml, which
no longer exists (ADR-0097). The binary is <dir>/<dir-name>, which is what
the scaffold's Makefile produces.
Pre-flight: refuses to launch if the runtime credential at
~/.gibson/<kind>/<name>.runtime.json is missing, and points at the two
environment variables that enrol a component at boot.
Exit codes are surfaced verbatim from the child.
Examples:
gibson component run --kind tool
gibson component run --kind plugin --dir ./my-plugin
gibson component run --kind agent --drain-timeout 60s
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
-d, --dir | string | . | component directory (containing the compiled binary) |
--drain-timeout | duration | 30s | max wait between SIGTERM and SIGKILL on shutdown |
--kind | string | — | component kind: agent | tool | plugin (required) |
gibson component validate
Local schema + proto checks against a component directory
validate runs kind-aware local checks against the component in --dir
(default: current directory).
--kind is required. It used to be auto-detected from component.yaml, which
no longer exists (ADR-0097): the kind is the only thing a component
directory cannot imply, so it is the one thing you still state.
agent: main.go is present and parses
tool: agent checks, plus proto field 100 = DiscoveryResult, plus
buf lint when buf is on PATH
plugin: Go source of package main at the root, and each file parses;
the plugin declares itself in code (ADR-0097)
Paths come from the directory rather than from a manifest: main.go at the
root, and the tool proto at
api/proto/gibson/tools/<name>/v1/<name>.proto, with <name> the directory
name minus hyphens.
Exit codes:
0 no errors
2 validation errors (one or more findings printed to stderr)
1 I/O / setup error (e.g. --kind missing, or an unusable directory name)
Examples:
gibson component validate --kind tool
gibson component validate --kind plugin --dir ./my-plugin
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
-d, --dir | string | . | component directory |
--kind | string | — | component kind: agent | tool | plugin (required) |
gibson connector
Manage tenant connectors (ConnectorService)
gibson connector — enable and manage connectors via
ConnectorService on the Gibson daemon (ADR-0114 Slice 4). Pick a connector
from the curated catalog and it becomes a running connector the operator
reconciles onto ToolHive. You do not write YAML. Authenticated as you: run `gibson login` first.
Subcommands:
catalog list the curated connectors this tenant may enable
enable enable a connector from the catalog by its catalog id
list list the tenant's enabled connectors and their live status
disable disable an enabled connector (removes the running connector)
gibson connector catalog
List the curated connectors this tenant may enable
Call ConnectorService.ListCatalog and print the curated
connectors this tenant may enable. The set is the shipped catalog, filtered
by the per-tenant catalog gate. Enable one with `gibson connector enable <id>`.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | RPC deadline |
gibson connector disable
Disable an enabled connector
Call ConnectorService.DisableConnector to disable an enabled
connector by its id. The operator cascade-removes the running connector, its
network policy, and its credential secret. This action is destructive: it
asks you to confirm unless you pass --yes.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | RPC deadline |
--yes | bool | — | Do not ask to confirm the disable |
gibson connector enable
Enable a connector from the catalog
Call ConnectorService.EnableConnector for a catalog entry
(for example `gibson connector enable gitlab`). The daemon creates
the connector in your tenant and the operator reconciles it onto ToolHive.
An OAuth connector comes up in the AuthorizationRequired phase until a person
authorizes it. The enabled connector id and its initial phase are printed.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | RPC deadline |
gibson connector list
List the tenant's enabled connectors and their live status
Call ConnectorService.ListConnectors and print the tenant's
enabled connectors with their live status: shape, runtime, lifecycle phase,
the count of discovered tools, and the last error (if any).
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | RPC deadline |
gibson docs
Emit machine-readable docs
docs — emit developer-facing reference material.
Subcommands:
cli the command tree as machine-readable JSON (drives the CLI reference)
gibson docs cli
Emit the command tree as machine-readable JSON
cli walks the whole gibson command tree and writes it to stdout as a
stable JSON document (sorted, deterministic). It is the source of truth
for the auto-generated CLI reference in the documentation site: the
generator renders the reference from this JSON, and a drift gate fails
if the committed page no longer matches.
Regenerate the committed spec after any command, flag, or help-text
change:
gibson docs cli > cli-spec.json
gibson init
Initialize a Gibson workspace (writes .gibson/workspace.yaml)
init writes a workspace.yaml that pins GIBSON_URL for this workspace,
so subsequent `gibson component <verb>` calls do not require
the flag every time.
By default the file is written to ./.gibson/workspace.yaml (per-project).
Pass --global to write to ~/.gibson/workspace.yaml (machine-wide
fallback).
The workspace file is non-secret. It MUST NOT contain client_id /
client_secret / bootstrap_token / host_key / password / secret / token
fields — Load() rejects them at parse time. Credentials live at
~/.gibson/{agent,tool,plugin}/credentials with mode 0600. Tenant
context is embedded in those credentials, so workspace.yaml carries
no tenant pin.
Examples:
gibson init --gibson-url https://api.zeroroot.ai
gibson init --global --gibson-url https://api.zeroroot.ai
gibson init --force --gibson-url ... # overwrite existing
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--comment | string | — | Optional free-form note. |
--force | bool | — | Overwrite an existing workspace file. |
--gibson-url | string | — | Gibson platform URL (e.g. https://api.zeroroot.ai). Required. |
--global | bool | — | Write to ~/.gibson/workspace.yaml instead of ./.gibson/workspace.yaml. |
gibson inspect
Show what this principal can do (calls WhoAmI on the Gibson daemon)
inspect loads the local runtime credential at
~/.gibson/<kind>/<name>.runtime.json (written by the component itself on
its first start, from GIBSON_URL and GIBSON_BOOTSTRAP_TOKEN), signs a per-RPC Capability-Grant JWT with the registered
agent key, and calls IdentityService.WhoAmI to print the principal's
effective Gibson permissions.
Auto-detection: when --kind is unset, inspect scans ~/.gibson/{agent,
tool,plugin}/*.runtime.json and, when exactly one exists, picks that.
Multiple installs require --kind (and --name). GIBSON_AGENT_KEY (a
base64 runtime credential) overrides the on-disk lookup for CI / k8s.
When no component credential exists and you ran gibson login, inspect
calls WhoAmI with your login session instead.
Output formats:
default human-friendly tree with stable action labels for grep
--json raw WhoAmIResponse as canonical proto-JSON (for scripts)
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | — | Emit raw WhoAmIResponse JSON instead of the tree |
--kind | string | — | agent | tool | plugin (auto-detected when only one exists) |
--name | string | — | Install name when multiple of the same kind exist |
gibson login
Authenticate the CLI against the Gibson platform (device flow)
login runs the OAuth 2.0 Device Authorization Grant against the
platform's identity service: it prints a URL + short code, you approve
in a browser, and the CLI stores the resulting session at
~/.gibson/auth/credentials (mode 0600). Every subsequent gibson command
then acts as you. The session refreshes silently; run gibson logout to
end it.
The CLI learns its issuer + public client_id from the platform
(GET {GIBSON_URL}/.well-known/gibson-login); pass --issuer/--client-id to
override for local or air-gapped setups. GIBSON_URL defaults to
https://api.zeroroot.ai; --gibson-url, the GIBSON_URL env var, or a
workspace file (gibson init) override it.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--client-id | string | — | Override the CLI OAuth client_id (skips platform bootstrap). |
--gibson-url | string | — | Gibson platform URL; falls back to GIBSON_URL, then the workspace, then https://api.zeroroot.ai. |
--issuer | string | — | Override the OIDC issuer (skips platform bootstrap). |
--no-browser | bool | — | Do not attempt to open a browser; just print the URL. |
--tenant | string | — | Assert the tenant you expect to sign in as; checked against your account, not selected by this flag. |
--timeout | duration | 10m0s | Overall deadline for the login flow. |
gibson logout
End the CLI session and remove stored credentials
gibson mission
Author, validate, render, and submit gibson missions
gibson mission — author missions in CUE / YAML / JSON
and submit them to the daemon.
Subcommands:
new scaffold a new mission (--from-template <name> | minimal)
validate run cue vet / proto validation against an input file
render compile the input to proto-shaped JSON or YAML
submit validate + define + run via the daemon (full CUE→define→run)
gibson mission catalog
List the missions the platform ships, or show one
The platform's own mission definitions, compiled into the daemon.
With no arguments, list them with the parameters each one declares.
With a name, print that mission's CUE — the source the daemon renders,
not a summary of it.
Submit one with:
gibson mission submit --catalog <name> --target <target-id> --param k=v
The parameter set is closed: an unknown key is refused rather than
dropped, so a typo cannot read as a value that bound.
gibson mission catalog list
List the missions the platform ships
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | Request deadline |
gibson mission catalog show
Print a shipped mission's CUE, or its rendered definition
Print the mission's CUE source, verbatim, so what the daemon will
run can be read rather than trusted.
With --rendered, print the rendered MissionDefinition as JSON instead.
That needs every parameter the mission declares, because rendering is
what validates them.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--param | stringArray | — | A parameter, as key=value. Repeatable. Required with --rendered, because rendering is what validates them |
--rendered | bool | — | Print the rendered MissionDefinition as JSON instead of the mission's CUE |
--timeout | duration | 30s | Request deadline |
gibson mission new
Scaffold a new mission file
Scaffold a new mission file.
With --from-template <name>, writes the named template's content. Use
--list-templates to see available templates. Without flags, writes a
minimal scaffold with FIXME placeholders.
The scaffold names a target, so what it writes submits as written. Pass
--target <name-or-uuid> to choose one; with no --target the command reads
your tenant's targets and uses the only one, or asks you to pick when there
is more than one. A UUID is taken as given and needs no daemon.
Pass --no-target to scaffold offline. The file then carries an empty
target_ref, and submit refuses it until you fill it in or pass --target.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--from-template | string | — | Name of a built-in template to scaffold from |
--gibson-url | string | — | Daemon URL (default: your login session's) |
--list-templates | bool | — | List available templates and exit |
--no-target | bool | — | Scaffold offline, leaving target_ref empty |
-o, --output | string | - | Output path; '-' for stdout |
--target | string | — | Target name or UUID to write into the scaffold |
--timeout | duration | 30s | Timeout for the target lookup |
gibson mission render
Compile a mission file to proto-shaped JSON or YAML
Render the input mission file as the canonical proto-shaped JSON
the daemon expects. With --out-format yaml, JSON is converted to YAML
via sigs.k8s.io/yaml (round-trip-equivalent).
Useful for:
- Reviewing what the daemon will see before submitting.
- Diffing two mission files semantically (compile both then diff JSON).
- Piping into other tooling (`gibson mission render m.cue | jq …`).
Output is deterministic: protojson controls proto field ordering (camelCase,
stable); encoding/json.Indent normalizes whitespace, eliminating the
binary-hash-seeded extra space that protojson's internal detrand inserts
after colons to make builds non-reproducible.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--format | string | — | Override input format detection: cue|yaml|json |
--out-format | string | json | Output format: json|yaml |
gibson mission submit
Validate, define, and run a mission via the daemon
Full CUE/YAML/JSON → define → run submit:
1. Load the mission. Either from a FILE (CUE / YAML / JSON detected
from the extension or --format), or from the platform's own
catalog with --catalog <name> --param k=v, which renders it
server-side.
2. Run protovalidate on the parsed *missionv1.MissionDefinition.
3. With --dry-run, print the rendered JSON and exit; otherwise:
4. Call DaemonService/CreateMissionDefinition to register the
definition and obtain a mission_definition_id.
5. Call DaemonService/CreateMission with the definition ID.
6. Print the returned mission ID.
A catalog mission is rendered by the daemon from the definition
compiled into its own binary (ADR-0118), so the graph is the
checked-in one rather than a copy. Its parameters are a closed set:
run `gibson mission catalog list` to see what each one
declares. A catalog mission declares no target, so --target is
required for it.
The daemon URL is taken from your login session (run `gibson login`
first); override it with --gibson-url. Production use should
route through the dashboard's Server Action path — this command
is the CLI escape hatch for development and CI.
Auth: the call is made over the authenticated login session
(bearer token only; the daemon resolves your tenant from your
account, not from this command); there is no plaintext or
unauthenticated path.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--catalog | string | — | Run a mission from the platform's catalog by name instead of from a file (list them with: gibson mission catalog list) |
--detach | bool | — | Return once the daemon has started the run and print the mission id; do not wait for the mission to finish |
--dry-run | bool | — | Print rendered JSON; do not contact the daemon |
--format | string | — | Override input format detection: cue|yaml|json |
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--param | stringArray | — | A --catalog mission's parameter, as key=value. Repeatable. The set is closed: an unknown key is refused |
--target | string | — | Target id to bind the mission to (overrides the definition's target_ref) |
--timeout | duration | 30s | Submit deadline |
gibson mission validate
Validate a mission file (CUE / YAML / JSON)
Validate a mission file.
Steps:
1. Read and parse the file (CUE → JSON via cuelang; YAML → JSON via
sigs.k8s.io/yaml; JSON passes through). Format detected from the
file extension; override with --format.
2. Unmarshal into *missionv1.MissionDefinition via protojson.
3. Run protovalidate against the message — every
(buf.validate.field).* annotation declared in the SDK protos
is enforced here, matching what the daemon applies at submit
time.
4. Check that target_ref, when set, is a target UUID. The daemon
rejects any other value.
5. Check that each starts_from names an earlier node: a node that
exists, is not the node itself, and is an ancestor of the node
through dependencies or edges (ADR-0169). The daemon applies the
same rule at submit time.
Exits non-zero with the underlying library's error message on any
failure. Use '-' as the file path to read from stdin.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--format | string | — | Override format detection: cue|yaml|json |
gibson secret
Store, list, rotate, and delete tenant secrets
gibson secret — manage the credentials your components use.
A secret is a NAME and BYTES. There is no type or format field: the thing that
reads a credential is the only party that knows what it needs, so it validates
by parsing (ADR-0096).
NAMES ARE EXACT. The name you give is the stored key, and it is also the
additional authenticated data of the secret's own envelope, so a name that
differs by one character is a different secret and a mistyped one is
unrecoverable. Nothing here trims or rewrites what you type.
Every name begins with a namespace:
cred:<name> a credential a component uses
provider_config:<provider>:<field> an LLM provider setting
`gibson secret list` prints exact keys, which are exactly what goes into a
mission's credential_names.
Subcommands:
set store a secret, from a file or stdin
get show one secret's metadata (never its value)
list list secret names and metadata (never values)
rotate store a new value for an existing secret
delete remove a secret
count how many secrets the active backend holds
backend show or configure which backend stores the secrets
gibson secret backend
Show or configure which backend stores the secrets
gibson secret backend — which store the tenant's secrets live in.
Two backends exist. Every other provider was retired and its enum value
reserved, so there is no AWS, GCP or Azure option to choose:
hosted the platform-managed OpenBao, isolated per tenant by namespace.
Zero configuration, and already active.
byo your own Vault or OpenBao, isolated by path prefix because OSS
Vault and OpenBao CE have no namespaces.
Subcommands:
show print the active configuration, with sensitive fields redacted
probe validate a candidate configuration WITHOUT saving it
set probe a candidate configuration and save it on success
gibson secret backend probe
Validate a candidate configuration without saving it
Check that a candidate backend configuration works, and change nothing.
Run this before `set`. A backend that cannot be reached and is saved anyway
leaves every secret unreadable until it is fixed.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--address | string | — | Vault/OpenBao address (byo) |
--approle-role-id | string | — | AppRole role id (auth-method approle) |
--approle-secret-id-file | string | — | File holding the AppRole secret id (auth-method approle) |
--auth-method | string | — | token or approle (byo) |
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--mount | string | — | KV mount (byo) |
--path-prefix | string | — | Path prefix that isolates this tenant (byo) |
--provider | string | — | hosted or byo |
--timeout | duration | 30s | Request deadline |
--token-file | string | — | File holding the Vault token (auth-method token) |
gibson secret backend set
Probe a candidate configuration and save it on success
Save a backend configuration, after the server probes it.
The server probes before it persists, so a configuration that cannot be reached
is refused rather than stored.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--address | string | — | Vault/OpenBao address (byo) |
--approle-role-id | string | — | AppRole role id (auth-method approle) |
--approle-secret-id-file | string | — | File holding the AppRole secret id (auth-method approle) |
--auth-method | string | — | token or approle (byo) |
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--mount | string | — | KV mount (byo) |
--path-prefix | string | — | Path prefix that isolates this tenant (byo) |
--provider | string | — | hosted or byo |
--timeout | duration | 30s | Request deadline |
--token-file | string | — | File holding the Vault token (auth-method token) |
gibson secret backend show
Print the active backend configuration, redacted
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | Request deadline |
gibson secret count
How many secrets the active backend holds
Count the secrets in the tenant's active backend.
This asks the backend rather than the metadata index, so it is the check for
whether a backend swap moved everything it should have.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | Request deadline |
gibson secret delete
Remove a secret
Remove a secret.
A job whose credential_names still declares this name will fail to resolve it
once it is gone, so check with `gibson secret get` before deleting a name you did
not create.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | Request deadline |
--yes | bool | — | Confirm the deletion |
gibson secret get
Show one secret's metadata (never its value)
Show a secret's metadata.
This never prints the value, and not because the CLI withholds it: the RPC does
not return it. The only RPC in Gibson that returns a plaintext credential is the
harness callback a sandboxed component uses, which is not callable from here.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | Request deadline |
gibson secret list
List secret names and metadata (never values)
List the tenant's secrets.
The names printed are exact stored keys, which is what a mission's
credential_names needs, so they can be copied without translation.
gibson secret list
gibson secret list --prefix cred:
When more secrets exist than one page holds, the command prints the token
of the next page. Pass it to --page-token to read that page.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--page-size | int32 | — | Maximum number to return (0 = server default) |
--page-token | string | — | Token of the page to read, from the previous page |
--prefix | string | — | Only names beginning with this prefix (e.g. cred:) |
--timeout | duration | 30s | Request deadline |
gibson secret rotate
Store a new value for an existing secret
Store a new value under an existing name, creating a new version.
Rotation keeps the name, which matters: the name is what a job's
credential_names declares, so rotating a credential needs no change anywhere
else.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--from-file | string | — | Read the value from this file |
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--stdin | bool | — | Read the value from stdin |
--timeout | duration | 30s | Request deadline |
gibson secret set
Store a secret, from a file or stdin
Store a secret under an exact name.
The name is the stored key and the envelope's AAD, so it is used verbatim —
nothing is trimmed. The namespace prefix determines the category; there is no
--category flag, because a category that disagreed with the prefix would write
a key nobody can read.
gibson secret set cred:goat-cluster --from-file ~/.kube/goat.yaml
kubectl config view --raw | gibson secret set cred:goat-cluster --stdin
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--from-file | string | — | Read the value from this file |
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--stdin | bool | — | Read the value from stdin |
--timeout | duration | 30s | Request deadline |
gibson target
Create, list, inspect, update, and delete assessment targets
gibson target — manage the systems your missions assess.
A target is identified by a server-minted UUID; the name and other fields are
metadata. Missions reference a target by its UUID — names are never resolved.
Subcommands:
create register a new target (prints the minted UUID)
list list your targets (UUID + metadata)
get show a single target by UUID
update replace a target's metadata by UUID
delete remove a target by UUID
gibson target create
Register a new target and print its minted UUID
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | — | Free-text description |
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--name | string | — | Human-readable target name (metadata) |
--provider | string | — | Backing provider (e.g. openai) |
--tag | stringSlice | — | Tag (repeatable) |
--target-timeout | int32 | — | Per-operation timeout in seconds |
--timeout | duration | 30s | Request deadline |
--type | string | — | Target type (e.g. llm_chat, custom) |
--url | string | — | Target endpoint URL |
gibson target delete
Remove a target by UUID
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | Request deadline |
gibson target get
Show a single target by UUID
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--timeout | duration | 30s | Request deadline |
gibson target list
List your targets (UUID + metadata)
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--page-size | int32 | — | Max results (0 = server default) |
--page-token | string | — | Token of the page to read, from the previous page |
--provider | string | — | Filter by provider |
--status | string | — | Filter by status |
--tag | stringSlice | — | Filter by tag (repeatable; target must carry all) |
--timeout | duration | 30s | Request deadline |
--type | string | — | Filter by type |
gibson target update
Replace a target's metadata by UUID
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | — | Free-text description |
--gibson-url | string | — | Override the daemon URL (defaults to the login session). |
--name | string | — | Human-readable target name (metadata) |
--provider | string | — | Backing provider |
--tag | stringSlice | — | Tag (repeatable) |
--target-timeout | int32 | — | Per-operation timeout in seconds |
--timeout | duration | 30s | Request deadline |
--type | string | — | Target type |
--url | string | — | Target endpoint URL |