---
title: "Choose the Right Surface"
url: "https://docs.caracal.run/runtime-console/cli-and-console/"
markdown_url: "https://docs.caracal.run/markdown/runtime-console/cli-and-console.md"
description: "Decide whether a task belongs in the runtime CLI, Console, Control API, or Admin SDK."
page_type: "reference"
concepts: []
requires: []
---

# Choose the Right Surface

Canonical URL: https://docs.caracal.run/runtime-console/cli-and-console/
Markdown URL: https://docs.caracal.run/markdown/runtime-console/cli-and-console.md
Description: Decide whether a task belongs in the runtime CLI, Console, Control API, or Admin SDK.
Page type: reference
Concepts: none
Requires: none

---

Use this page before reaching for a command. Caracal separates local runtime lifecycle from product management so workload execution does not depend on admin tokens or selected zones.

## Ownership Rule

```text
local lifecycle and process execution -> caracal
human product management              -> caracal console / caracal-console
scripted product management           -> Control API or Admin SDK
```

The top-level runtime CLI intentionally contains only `up`, `down`, `status`, `purge`, `run`, and `console`.

:::note[FAQ]
[Why are zone and policy commands in the Console instead of the `caracal` CLI?](/reference/faq/#faq-015)
:::

## Runtime CLI Tasks

| Outcome | Command |
| --- | --- |
| Start the local stack | `caracal up` |
| Stop the local stack | `caracal down` |
| Stop and remove volumes | `caracal down -v` |
| Probe service health | `caracal status` |
| Probe dependency readiness | `caracal status --ready` |
| Emit structured status | `caracal status --json` |
| Remove local stack/runtime state | `caracal purge` |
| Run a process with resource tokens | `caracal run -- <command>` |
| Open the Console | `caracal console` |

Runtime CLI commands must not require admin tokens, selected zones, product credentials, or Control credentials.

## Console Tasks

| Outcome | Console menu |
| --- | --- |
| Create or select zones | `zone` |
| Register confidential agent applications | `application` |
| Configure provider credential sources | `provider` |
| Register protected resources and scopes | `resource` |
| Author access policies | `policy` |
| Simulate and activate policy sets | `policy set` |
| Inspect authority sessions | `authority session` |
| Enable and manage Control API access | `control` |
| Search audit records and trace selected requests | `audit` |
| Trace one known request ID | `request trace` |
| Inspect or manage agent sessions | `agent session` |
| Inspect or revoke delegation edges | `delegation` |
| Run health, readiness, zone, and preflight checks | `diagnostics` |

Product-management workflows are not mirrored as top-level runtime CLI commands. Keeping them in the Console prevents command drift and keeps interactive operations tied to the same engine/admin helpers.

## Automation Tasks

Use the Admin SDK from trusted operator environments when scripts need to create zones. Use the Control API for zone-bound automation over applications, resources, policies, authority sessions, agents, delegation edges, audit queries, and Control credentials. Enable Control from the Console `control` menu, then call the authenticated HTTP surface from CI or automation.

Automation must run with operator credentials only in trusted control-plane environments. Agent workloads should use `caracal run` or application credentials and must not receive `CARACAL_ADMIN_TOKEN`, `CARACAL_COORDINATOR_TOKEN`, `CARACAL_SECRETS_DIR`, or mounted operator secret files.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| `caracal console` is hidden or unavailable | Use `caracal-console` directly, or reinstall so the Console binary/workspace shim is available. Runtime lifecycle commands remain available. |
| A command for zones, policies, or audit is missing from `caracal` | Open the Console. Those workflows are intentionally Console-owned. |
| Console fails in CI | Use the Control API or Admin SDK. The Console requires an interactive TTY. |
| Runtime command asks for product-management context | Treat it as a bug; runtime lifecycle must not depend on admin or zone state. |

## Next Step

Use [Start and Check the Stack](/runtime-console/stack/) when you need local services running.