Reference

CLI reference

Each sentinel command and each option.

The sentinel command uses the Sentinel interface. It also runs a local Cortex proxy, with no cluster.

To install the program, see Install the cluster CLI.

sentinel --help
sentinel version
sentinel install        # Prints the instructions to install the platform

The global options#

Option	Function
`--server URL`	Uses this server and not the server of the current context.
`--context NAME`	Uses a named context, with its server, its token and its namespace. The option can be before or after the subcommand.
`--json`	Returns JSON. Most read commands accept this option.

Contexts#

The command stores each server, namespace and token as a named context in ~/.config/sentinel/config.toml. The arrangement is the arrangement that kubectl uses. The command stores each credential separately, in ~/.local/state/dam/auth.toml.

sentinel config get-contexts
sentinel config create-context --name dev \
    --server http://my-host:8080/api/v1/ --namespace team1 --bearer-token <token>
sentinel config use-context dev
sentinel config set-context --namespace team1
sentinel config set-context --namespace team1 --server http://other:8080/api/v1/
sentinel config set-context --name prod      # Renames the current context

The create-context command makes the new context current. The set-context --namespace command gives a warning if the server does not have that namespace.

An empty list is correct

The get-contexts command creates nothing. It therefore prints an empty table until a different command creates the configuration. That command creates two contexts. The first context is for the default server and becomes current. The second context is a local context with the name cortex.

Authentication#

sentinel login                                   # An OAuth device flow against Keycloak
sentinel login --token <token>                   # Sets a token on the current context
sentinel login --server http://host:8080/api/v1/ --token <token>
sentinel login --cortex                          # Selects the local cortex context

The login --server command selects the context for that host. It creates the context if the context is absent, and then makes it current.

The cortex context needs no server and no token. The command answers each request inside its own process, from the records that authbridge exec wrote. The cortex serve command and the authbridge exec command both create the context if it is absent. The cortex serve command also makes it current. The authbridge exec command does not, because that command runs a different program and must not change the context for a later command.

Examine your token#

sentinel auth status                # The name, the user name, the address, the issuer, the expiry time, the audiences, the roles and the scopes
sentinel auth status --json         # The claims as JSON
sentinel auth status --context prod

The command reads the token on your computer. It sends nothing.

sentinel auth token                 # Prints the token and nothing else

Warning

The auth token command writes a credential to the standard output. A terminal keeps that output in its history, and a build pipeline keeps it in the build log.

The command exits with an error when the context has no token. A shell substitution therefore fails, and does not produce an empty value.

curl -H "Authorization: Bearer $(sentinel auth token)" \
  "http://my-host:8080/api/v1/agents?namespace=team1"

Examine the server#

sentinel auth-config                # Reads <server>/auth/config
sentinel auth-config --json
sentinel status                     # The current session and the state of the platform
sentinel status --json

Agents#

sentinel agents list                          # The namespace of the context, or --namespace
sentinel agents --namespace team2 list
sentinel agents list --all-namespaces         # -A: reads /namespaces, then lists each one
sentinel agents list --no-headers             # Omits the header row
sentinel agents get orders                    # One agent, in a single column
sentinel agents get orders --json
sentinel agents delete orders

With the --no-headers option, the message "no agents found" goes to the standard error. The standard output is therefore empty when there is no agent, and a pipeline receives no row:

sentinel agents list --no-headers | awk '{print $1}' | xargs -n1 sentinel agents delete

Wait for an agent#

sentinel agents wait orders
sentinel agents wait orders --timeout 5m      # The default is 60s. Use 0 to wait without a limit.
sentinel agents wait orders -v                # Reports the progress on the standard error

The command reads the state every 2 seconds. It exits with the code 0 when the agent is ready. You can therefore put it in a sequence:

sentinel agents import from-image --name orders --containerImage ghcr.io/x/y:latest \
  && sentinel agents wait orders --timeout 5m \
  && ./run-integration-tests.sh

The command exits with an error when the agent cannot become ready. The three causes are a failed build, a rollout that passed its time limit, and a name that the server does not have. An immediate error is more useful than an error after the time limit.

Import an agent#

sentinel agents import from-image --name orders --containerImage ghcr.io/x/y:latest

sentinel agents import --deployment-type sandbox from-image \
    --name orders --containerImage ghcr.io/x/y:latest \
    --imagePullSecret regcred \
    --envVarsURL https://example.com/orders.env

Option	Function
`--containerImage`	The address of the image.
`--imagePullSecret`	The Secret for a private registry.
`--envVar KEY=VALUE`	Sets one variable. You can repeat the option. The value is literal, and can contain a comma.
`--envVarsURL URL`	Reads `key=value` lines from an address.
`--deployment-type`	Selects `deployment`, `statefulset` or `sandbox`.
`--context NAME:PATH`	Attaches an agent context.
`--additionalParameterJSON`	Sends a field that has no option.

If --envVar and --envVarsURL set the same variable, --envVar wins. The order of the options does not change this result:

sentinel agents import from-image --name orders --containerImage ghcr.io/x/y:latest \
    --envVar LOG_LEVEL=debug --envVar 'TAGS=a,b,c'

The --additionalParameterJSON option accepts a JSON object, or the name of a file that contains one. A value that starts with { is the object. Each other value is a file name.

You can repeat the option. The command combines the objects. A later object replaces a key that it shares with an earlier object. The command then adds the result to the request. The combination uses the top-level keys, so a repeated key replaces the complete value. A key that names a field that an option also sets replaces the value of that option.

sentinel agents import from-image --name orders --containerImage ghcr.io/x/y:latest \
    --additionalParameterJSON ./base.json \
    --additionalParameterJSON '{"containerImage":"ghcr.io/x/y:pinned"}'

The Cortex configuration of an agent#

sentinel agents authbridge get orders          # The mode, and the two chains in execution order
sentinel agents authbridge get orders --json
sentinel agents authbridge set orders --policy-file ./authbridge.yaml
sentinel agents authbridge set orders --policy-file ./authbridge.yaml --wait

The --policy-file option is necessary. The command sends the file as text/plain and without a change. Your comments and your key order therefore remain, and the server validates the file.

The --wait option reads the configuration before the write. It then reads the configuration every 2 seconds until the result differs from that first value. It stops after 2 minutes.

The comparison uses the first value and not the file. The file is YAML for a ConfigMap. The read returns the JSON that the sidecar gives, and the sidecar removes each secret from that JSON. The signal is therefore a change. The command cannot confirm a configuration that is already active. In that case it reaches its time limit and exits with an error.

Tools#

The tools commands operate on the /tools endpoint. The --namespace, --context, --all-namespaces, --json and --no-headers options operate in the same way.

sentinel tools list
sentinel tools list --all-namespaces
sentinel tools get weather-mcp
sentinel tools wait weather-mcp --timeout 10m
sentinel tools delete weather-mcp
sentinel tools import from-image --name weather-mcp --containerImage ghcr.io/x/y:latest

The --ports option sets the service ports. The format is name:port:targetPort[:protocol]. The default is http:9090:9090:TCP. A number alone means http:<port>:<port>:TCP:

sentinel tools import from-image --name weather-mcp --containerImage ghcr.io/x/y:latest \
    --ports grpc:9000:9001:TCP,8080

A tool that Sentinel builds from source reports Building until the build ends. A build often needs more time than the default limit of 60 seconds. Give a longer limit. If the build fails, the command reports Build Failed and exits at once.

Note

Against the local cortex context, the tools wait command reaches its time limit. That server does not have the endpoint that the command reads, and the tools get command fails for the same reason. Use tools list for a local tool. The agents wait command operates correctly.

Namespaces#

sentinel namespaces list

Agent context#

sentinel context storage-classes
sentinel context create research --shared --size 10Gi --storage-class ibm-scale-csi
sentinel context list
sentinel context get research
sentinel context delete research

sentinel agents import --deployment-type sandbox \
    --context research:/workspace \
    from-image --name researcher --containerImage IMAGE

See Agent context.

Cortex on your computer#

sentinel authbridge exec --config ./authbridge.yaml -- claude "explain this repo"
sentinel authbridge exec --config https://example.com/authbridge.yaml -- ./script.sh --verbose

The --config option is necessary. It accepts a local YAML file or an address that serves YAML. For an address, the command writes the content to a temporary file and deletes that file when it exits.

The command gives each argument after -- to your program without a change. It exits with the exit status of your program.

The command sets HTTP_PROXY for the proxy. It sets HTTPS_PROXY and the certificate variables also when the TLS bridge runs. The certificate variables are NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE and SSL_CERT_FILE. The command does not change a variable that you already set. It stops each part when your program exits, and also on a SIGINT signal or a SIGTERM signal.

Option	Function
`--config FILE\\|URL`	Necessary. The configuration of the chain.
`--with-claude-otel`	Also sets the variables that make Claude Code send traces to the local collector.
`--logfile PATH`	The log of Cortex. The default is `/tmp/authbridge.log`. Use `""` for the standard error.

The log goes to a file and not to the standard error, so it does not mix with the output of your program. The command prints the path at the start.

Traces#

sentinel otel collect
sentinel otel collect --traces_endpoint http://host.containers.internal:5002/v1/traces
sentinel otel send-mock-trace
sentinel otel send-mock-trace --serviceName my-agent
sentinel otel send-mock-trace --url http://localhost:14318/v1/traces

The otel collect command writes a configuration file to ~/.config/sentinel/otel. It then starts the OpenTelemetry collector with that file. The collector receives OTLP on port 4317 for gRPC and on port 4318 for HTTP. The command needs docker or podman on your path. The container runs in the background. To stop it, use podman stop or docker stop with the name that the command printed.

The default --traces_endpoint value reaches your computer from inside the container. Inside the container, the name localhost means the collector.

The command records two values in ~/.config/sentinel/otel-config.yaml. The first value is the path of the configuration file. The second value is the address that a client uses to reach the collector, which is 127.0.0.1:4318. That address is the address to send to, and not the 0.0.0.0 address that the collector listens on inside the container.

The send-mock-trace command sends one span. Use it to test the path from your computer to your trace store, without an agent. The --serviceName option sets the service.name attribute. A trace store groups the traces by that attribute, so it is the name that your span has in the interface. Each command uses new identifiers, so each command produces a separate trace.

See Observability.