graphenectl

graphenectl is the control CLI of a graphene installation. It manages records: resources with their five dimensions, runs, secrets, namespaces, connection contexts. Its stance and grammar are kubectl's — the verb comes first, the kind second.

What it deliberately does not do: build, push, or start your pipeline from source. The pipeline binary manages its own pipeline — ./your-pipeline push, ./your-pipeline run — using the same connection contexts. graphenectl run start starts a run of an already pushed pipeline: the worker image comes from the pipeline record, no checkout needed.

Install

graphenectl is a single static binary built from the graphene repository:

$ go build -o ~/bin/graphenectl ./cmd/graphenectl

First contact

$ echo $TOKEN | graphenectl login --server graphene.example:7233 --token-stdin
logged in: context graphene.example, role run, namespace team

login verifies the server and the token with a handshake before writing anything, then saves the context and makes it current. See Contexts.

Wire the shell completion right away — the grammar, the kinds, and the ids all complete, so nobody guesses (graphenectl get d<TAB> offers docker, docker-volume, docker-network even before any records exist — the kinds come from the pipelines' manifests):

$ source <(graphenectl completion bash)     # zsh and fish: see Project commands

Grammar

graphenectl <verb> <kind> [id] [flags]     # records
graphenectl run <lifecycle-verb> ...       # run lifecycle
graphenectl <noun> <verb> ...              # ctx, secret, ns, pipeline

A record target is written either as two words or as one ref:

$ graphenectl get docker-volume my-vol
$ graphenectl get docker-volume/my-vol     # the same

A run is a record like any other — kind run: get run, get run <id>, events run <id> all work. Only the lifecycle verbs live under run (start, watch, result, cancel, list), the way kubectl keeps rollout apart.

Conventions

• stdout is data, stderr is progress. Pipe stdout anywhere; the human-facing chatter never contaminates it.
• Exit codes: 0 success, 1 failure — a watched run's terminal status maps to the exit code.
• Flags parse on either side of positionals: graphenectl secret set demo --value x and graphenectl secret set --value x demo are the same command.
• Common failures print a one-line hint: with the next step:

$ graphenectl ns list
graphenectl: unauthenticated: 401 Unauthorized
  hint: the token was rejected — check `graphenectl ctx show`, or re-run `graphenectl login`

The pages

Page	What lives there
Contexts	login, ctx, the config file and the environment chain
Connection flags	--context, --config, -n — on every network command
Output forms	-o table|wide|name|json|yaml, --jq, -w, --chunk-size
get	listing records and reading one
Observing	events, logs, metrics, trace
tree	the ownership tree
Lifecycle verbs	delete, transfer, invoke
run	starting and following runs
pipeline	the pipeline record
secret, ns	secrets and namespaces
Project commands	init, completion, version