rossoctl-cli

A command-line interface for Rossoctl, built with Cobra.

Install

The downloadRossoctl script downloads the release archive for your platform extracts it, and installs the binary at $HOME/.config/rossoctl/rossoctl:

curl -fsSL https://raw.githubusercontent.com/rossoctl/rossoctl-cli/main/downloadRossoctl | sh
PATH=$PATH:$HOME/.config/rossoctl
# alternately, sudo mv $HOME/.config/rossoctl /usr/local/bin

Quick usage, for shared OpenShift Rossoctl API servers

# (Choose w3id for shared cluster login)
rossoctl --server https://rossoctl-ui-rossoctl-system.apps.ykt3.hcp.res.ibm.com/api/v1 login
rossoctl agents list

Quick usage, for existing Kind cluster Rossoctl API server

rossoctl login
rossoctl agents list

Running a command behind an AuthBridge pipeline

# `--config` is required and takes a local YAML file or a URL serving YAML (a
# remote config is fetched to a temp file, which is removed on exit). Everything
# after `--` is passed through to the command untouched, and rossoctl exits with
# the command's exit status.
rossoctl authbridge exec --config ./authbridge.yaml -- claude "explain this repo"
rossoctl authbridge exec --config https://example.com/authbridge.yaml -- ./script.sh --verbose

What authbridge exec starts, driven by the config:

Config	What starts
listener.roles includes forward	forward proxy on listener.forward_proxy_addr (feeds traffic through the outbound pipeline)
tls_bridge.mode not disabled/empty	TLS bridge, so the pipeline sees decrypted HTTPS instead of an opaque CONNECT tunnel
session.enabled not false	session store, plus the session API on listener.session_api_addr when set

A listen address of port 0 is resolved to the port the kernel actually assigned, so an ephemeral proxy is still dialable by the hosted command.

--sessionServer overrides the session API address when given explicitly (defaulting to localhost:9094, which leaves the config's own address alone):

# Serve the session API somewhere else, even if the config disabled sessions.
rossoctl authbridge exec --sessionServer 127.0.0.1:9500 --config ./authbridge.yaml -- claude

# Turn session tracking off entirely.
rossoctl authbridge exec --sessionServer "" --config ./authbridge.yaml -- claude

The command's environment is pointed at whatever started: HTTP_PROXY for the forward proxy, plus HTTPS_PROXY and the CA trust variables (NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, SSL_CERT_FILE) when the TLS bridge runs. Variables already set in your environment are left alone. Everything is shut down when the command exits or on SIGINT/SIGTERM.

Authbridge's own log output goes to --logfile (default /tmp/authbridge.log) rather than stderr, so it does not interleave with the hosted command's output. The path is printed at startup; pass --logfile "" to log to stderr instead.

Plugins are compiled in via one blank import per plugin, matching the authbridge binaries — including context-guru, which those binaries keep opt-in but which rossoctl links by default so the context-guru demos run without a special build. Drop any of them with its exclude tag:

go build -tags exclude_plugin_opa,exclude_plugin_contextguru

Note that go run reports its own exit status, not the command's, so it collapses any non-zero status to 1. Use a built binary when the exit code matters.

Usage

rossoctl --help
rossoctl version
rossoctl agents --help

# Print instructions for installing the platform (clone + per-cluster setup script)
rossoctl install

# Manage contexts (persisted in ~/.config/rossoctl/config.yaml, kubectl-style)
rossoctl config get-contexts                    # created + seeded on first use
rossoctl config create-context --name dev \
    --server http://my-host:8080/api/v1/ --namespace team1 --bearer-token <token>   # becomes current
rossoctl config use-context dev
rossoctl config set-context --namespace team1   # set namespace on current context (warns if unknown to server)
rossoctl config set-context --namespace team1 --server http://other:8080/api/v1/   # also replace the server
rossoctl config set-context --name prod          # rename the current context (updates the current reference)
rossoctl login --token <token>                  # set the token on the current context directly
rossoctl login                                  # or: OAuth device flow against the server's Keycloak
rossoctl login --server http://host:8080/api/v1/ --token <token>   # target the context for that host (create if absent), make it current

# Show the server's auth configuration (GET <server>/auth/config)
rossoctl auth-config
rossoctl auth-config --json
rossoctl --server http://my-host:8080/api/v1/ auth-config

# Show current session + platform status, mirroring the web UI admin page
# (GET <server>/auth/status, /auth/me, /config/platform-status)
rossoctl status
rossoctl status --json                          # raw API data as JSON

# List agents (GET <server>/agents)
rossoctl agents list                            # single namespace: agents --namespace, else current context
rossoctl agents --namespace team2 list          # list one specific namespace
rossoctl agents list --all-namespaces           # -A: discover via GET /namespaces, list across all
rossoctl agents list --all-namespaces --json    # each namespace's response, separated by ---

# Show one agent (GET <server>/agents/<namespace>/<name>)
rossoctl agents get orders                      # single-column text, laid out like the web detail page
rossoctl agents get orders --json               # raw JSON

# Delete an agent (DELETE <server>/agents/<namespace>/<name>)
rossoctl agents delete orders

# Import an agent from a container image (POST <server>/agents)
rossoctl agents import from-image --name orders --containerImage ghcr.io/x/y:latest
rossoctl agents import --deployment-type sandbox from-image \
    --name orders --containerImage ghcr.io/x/y:latest --imagePullSecret regcred \
    --envVarsURL https://example.com/orders.env   # newline-separated key=value

# `agents --namespace` overrides the context's namespace for any agents subcommand
rossoctl agents --namespace team2 get orders    # -> GET /agents/team2/orders

# `--context` is a top-level flag: it uses a named context instead of the current
# one (its server, token, namespace). It may appear before or after the subcommand.
rossoctl --context prod agents get orders
rossoctl agents --context prod get orders               # equivalent
rossoctl --context prod agents --namespace teamX list   # --namespace still overrides the context's namespace

# Tools mirror the agents commands, against the /tools endpoint.
# --namespace, --context, --all-namespaces (-A), and --json behave as for agents.
rossoctl tools list                              # single namespace (context, or --namespace)
rossoctl tools list --all-namespaces             # discover and list across all
rossoctl tools --namespace team2 list --json
rossoctl tools get weather-mcp                   # GET /tools/<namespace>/weather-mcp (single-column detail)
rossoctl tools get weather-mcp --json            # raw JSON response
rossoctl tools delete weather-mcp                # DELETE /tools/<namespace>/weather-mcp
rossoctl tools import from-image --name weather-mcp --containerImage ghcr.io/x/y:latest  # POST /tools
rossoctl tools import --deployment-type statefulset from-image \
    --name weather-mcp --containerImage ghcr.io/x/y:latest --envVarsURL https://example.com/tool.env
# --ports sets service ports as name:port:targetPort[:protocol] (default http:9090:9090:TCP); a bare "port" = http:port:port:TCP
rossoctl tools import from-image --name weather-mcp --containerImage ghcr.io/x/y:latest --ports grpc:9000:9001:TCP,8080

# List namespaces (GET <server>/namespaces)
rossoctl namespaces list
rossoctl namespaces list --all      # include non-rossoctl-enabled namespaces
rossoctl namespaces list --json

# Log the underlying REST requests to stderr
rossoctl -v agents list

Full docs

See the documentation