Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

observal admin

Manage server settings, users, security policy, SSO, audit data, and the submission review queue.

All 24 workflows support --output table|json. JSON mode never prompts or emits progress banners. Destructive JSON commands require --force or --yes.

Core administration requires the admin role. Review commands are also available to global reviewers and authorized teamspace owners or reviewers. Some role changes require super_admin.

Commands

Command
Purpose

settings

List dynamic server settings

set

Create or update a dynamic setting

users

List users

create-user

Create a password-auth user

reset-password

Reset or generate a user password

delete-user

Permanently delete a user

set-role

Change a user role

diagnostics

Show database, key, and runtime health

trace-privacy

Show trace-redaction policy

trace-privacy-set

Change trace-redaction policy

cache-clear

Clear server caches

saml-config

Show redacted SAML configuration

saml-config-set

Create or replace SAML configuration

saml-config-delete

Delete SAML configuration

scim-tokens

List SCIM token metadata

scim-token-create

Create a one-time SCIM bearer token

scim-token-revoke

Revoke a SCIM token

security-events

Query security events

audit-log

Query compliance audit events

audit-log-export

Export audit events as CSV or JSON

review list

List pending submissions

review show

Show one submission

review approve

Approve a component, Agent, or bundle

review reject

Reject a component, Agent, or bundle

Settings

settings returns the direct settings array. Sensitive values are redacted by the server. set returns the server setting object and never echoes the supplied value in human output.

A positional setting value may be retained by shell history. Prefer deployment secret files for sensitive settings that support external management.

Users and roles

List users:

Create a user and let the server generate a password:

Supported roles are super_admin, admin, reviewer, and user.

Create with a chosen password only when shell-history exposure is acceptable:

Reset interactively in human mode:

Generate a password without prompting:

JSON reset requires --generate. Created and generated passwords are returned once. Treat the entire result as a secret and do not paste it into logs, issues, or chat.

Change a role:

Delete a user:

Human deletion prompts unless --force or --yes is present. JSON deletion requires confirmation through one of those flags.

Diagnostics and policy

diagnostics returns the direct health object. Trace privacy responses return trace_privacy. Cache clear returns the number of cleared entries.

SAML

Show redacted configuration:

Create or replace configuration:

Every update requires the IdP entity ID, SSO URL, and X.509 certificate. Optional flags include --idp-slo-url, --sp-entity-id, --jit|--no-jit, and --active|--inactive. Certificate and private-key material is never returned by configuration reads.

Delete configuration:

JSON deletion requires --force or --yes.

SCIM tokens

List results contain metadata and token prefixes only. Creation returns the plaintext bearer token once. Treat that result as a secret. Revocation requires a complete UUID and prompts in human mode unless forced.

Security events

Severity accepts info, warning, or critical. Limit accepts 1 through 1,000 and offset accepts zero or greater. JSON returns the server envelope with events and total.

Audit log

Query events:

Available filters are action, actor, resource type, sensitivity, outcome, source, start date, and end date. Source accepts server or cli. Limit accepts 1 through 500.

Print CSV to stdout:

Write CSV atomically:

Print JSON:

Write JSON atomically:

Existing files prompt in human mode. JSON mode fails with a conflict unless --force or --yes is provided. Audit exports can contain sensitive administrative data.

Review queue

List pending submissions:

Component types are mcp, skill, hook, prompt, and sandbox. Tabs are agents and components. A component type cannot be combined with the Agents tab.

The list refreshes the review row cache, including when empty. Row numbers can then be used by other review commands.

Show a submission:

The JSON detail may include submitted configuration, headers, or environment-variable declarations. Handle review data as potentially sensitive.

Approve:

Reject with a reason containing 1 through 5,000 characters:

--agent and --bundle are mutually exclusive. Approval and rejection return the direct server decision object.

Exit codes

Code
Meaning

3

Authentication required or failed

4

Administrator or reviewer permission denied

5

User, token, setting, review, or configuration not found

6

Ambiguous reference or existing export conflict

7

Invalid role, filter, UUID, SAML input, reason, or missing non-interactive confirmation

8

Rate limit reached

9

Server, database, ClickHouse, Redis, or filesystem unavailable

10

CLI and server version mismatch

Related

  • observal auth: inspect the active account and role

  • observal inbox: review and security notifications

  • observal ops: sessions, telemetry, logs, and insights

Previousobserval ops
Nextobserval doctor

Last updated

Was this helpful?