> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/cli-reference/admin.md). # 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 ```bash observal admin settings --output json observal admin set review.require_approval true --output json ``` `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: ```bash observal admin users --output json ``` Create a user and let the server generate a password: ```bash observal admin create-user alice@example.com 'Alice Smith' --role user --output json ``` Supported roles are `super_admin`, `admin`, `reviewer`, and `user`. Create with a chosen password only when shell-history exposure is acceptable: ```bash observal admin create-user alice@example.com 'Alice Smith' --password 'chosen-password' --output json ``` Reset interactively in human mode: ```bash observal admin reset-password alice@example.com ``` Generate a password without prompting: ```bash observal admin reset-password alice@example.com --generate --output json ``` 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: ```bash observal admin set-role alice@example.com reviewer --output json ``` Delete a user: ```bash observal admin delete-user alice@example.com --force --output json ``` Human deletion prompts unless `--force` or `--yes` is present. JSON deletion requires confirmation through one of those flags. ## Diagnostics and policy ```bash observal admin diagnostics --output json observal admin trace-privacy --output json observal admin trace-privacy-set true --output json observal admin cache-clear --output json ``` `diagnostics` returns the direct health object. Trace privacy responses return `trace_privacy`. Cache clear returns the number of cleared entries. ## SAML Show redacted configuration: ```bash observal admin saml-config --output json ``` Create or replace configuration: ```bash observal admin saml-config-set \ --idp-entity-id 'https://idp.example.com/entity' \ --idp-sso-url 'https://idp.example.com/sso' \ --idp-x509-cert "$(cat idp-cert.pem)" \ --active \ --output json ``` 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: ```bash observal admin saml-config-delete --force --output json ``` JSON deletion requires `--force` or `--yes`. ## SCIM tokens ```bash observal admin scim-tokens --output json observal admin scim-token-create --description 'Okta' --output json observal admin scim-token-revoke 11111111-1111-1111-1111-111111111111 --force --output json ``` 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 ```bash observal admin security-events --limit 50 --offset 0 --output json observal admin security-events --type auth.login.failure --severity critical --output json observal admin security-events --actor alice@example.com --output json ``` 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: ```bash observal admin audit-log --limit 100 --offset 0 --output json observal admin audit-log --actor alice@example.com --resource-type agent --output json observal admin audit-log --source cli --outcome success --output json observal admin audit-log --start-date 2026-08-01 --end-date 2026-08-31 --output json ``` 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: ```bash observal admin audit-log-export ``` Write CSV atomically: ```bash observal admin audit-log-export --file audit.csv ``` Print JSON: ```bash observal admin audit-log-export --output json ``` Write JSON atomically: ```bash observal admin audit-log-export --output json --file audit.json ``` 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: ```bash observal admin review list --output json observal admin review list --type mcp --output json observal admin review list --tab agents --output json observal admin review list --team-id 11111111-1111-1111-1111-111111111111 --output json ``` 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: ```bash observal admin review show 1 --output json ``` The JSON detail may include submitted configuration, headers, or environment-variable declarations. Handle review data as potentially sensitive. Approve: ```bash observal admin review approve 1 --output json observal admin review approve AGENT_UUID --agent --output json observal admin review approve BUNDLE_UUID --bundle --output json ``` Reject with a reason containing 1 through 5,000 characters: ```bash observal admin review reject 1 --reason 'Missing environment variable documentation' --output json observal admin review reject AGENT_UUID --agent --reason 'Unsafe prompt' --output json observal admin review reject BUNDLE_UUID --bundle --reason 'License conflict' --output json ``` `--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`](/cli-reference/auth.md): inspect the active account and role * [`observal inbox`](/cli-reference/inbox.md): review and security notifications * [`observal ops`](/cli-reference/ops.md): sessions, telemetry, logs, and insights --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.observal.io/cli-reference/admin.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.