CDP

The Cerebel Development Platform, or CDP, is the local developer CLI for bringing up a Cerebel, choosing a communication profile, and talking to it from the terminal.

This page is the working contract for the current MVP. If the implementation changes, update this page first so the team keeps the same terminology and command expectations.

For the review-first file format specification, see Domain Bundle File Formats.

Pre-v1 policy:

1. CDP schema and config contracts are allowed to break while we iterate.
2. When we adopt a standard, we switch fully instead of carrying compatibility fallbacks.

Terms

CDP : Cerebel Development Platform. The developer-facing CLI and local harness for booting and interacting with a Cerebel.

Cerebrum : The booted runtime instance managed by RAS and surfaced by CDP.

Domain : The logical context selected by CDP at boot time.

Domain Bundle : The folder-scoped configuration unit for one Domain. A Domain Bundle lives under config/domains/<domain_id>/ and includes cerebrum.md plus cortices/*.md markdown files.

Profile : The selected communication cortex profile. Profiles let you choose which chat-facing cortex CDP should use for a given session.

Install

CDP is installed as part of the docs-and-dev workflow for the repository.

Recommended local setup

uv sync --extra dev
make activate

The first command installs dependencies into the project environment. The second command activates the virtual environment so you can run cdp directly from the shell.

Run without activation

You can also invoke the CLI through uv:

uv run cdp status

Core workflow

The MVP flow is:

1. Choose a profile.
2. Boot the runtime with cdp up.
3. Start an interactive chat session with cdp chat.
4. Stop the runtime with cdp down.

uv run cdp profiles list
uv run cdp up --domain demo --profile cli
uv run cdp chat "hello"
uv run cdp down

Commands and options

cdp up

Boots the local Cerebrum runtime.

Option	Meaning
--domain <domain_id>	Selects the Domain Bundle root at config/domains/<domain_id>/. If omitted, CDP falls back to the configured default domain.
--profile <profile>	Selects the active communication profile for the boot session. If omitted, CDP uses the saved active profile or the default profile from config/defaults.json.

Example:

uv run cdp up --domain demo --profile cli

cdp chat

Starts a chat session through the active communication cortex for the current booted session.

Option	Meaning
message	The message to send to the current session.

If you pass a message, CDP sends one response and exits. If you omit the message, CDP enters a simple interactive prompt in the current terminal and stays open until you type exit, quit, or press Ctrl-D.

Example:

uv run cdp chat "hello cerebrum"

Interactive example:

uv run cdp chat

cdp down

Stops the local runtime and clears the active boot session.

cdp status

Shows the current runtime state, including the active domain, profile, and boot identity.

cdp profiles list

Lists the available communication profiles.

cdp profile use <profile>

Sets the active profile for future cdp up commands.

cdp logs [service]

Shows log output for the current runtime or a selected service.

cdp notebook open

Prints the notebook URL for the local developer environment.

cdp metrics

Prints the metrics endpoint URL for the local developer environment.

Current MVP guarantees

The current CLI behavior is intentionally strict:

1. cdp chat only works after cdp up.
2. cdp chat uses the profile selected for the active session.
3. cdp chat stays in the current terminal unless you decide to open a second terminal.
4. cdp down ends the active session.

These rules are the shared contract for the current MVP and are the baseline for future boot and conversation work.

Working with logs while chatting

The chat session is intentionally terminal-based, not a separate window.

If you want to inspect logs while chatting, open a second terminal or split pane and run cdp logs there. That keeps the chat session alive in the first terminal while you review runtime output in the other.

Domain Bundle Format

CDP now uses a forced directory layout for each Domain Bundle:

config/domains/
  <domain_id>/
    cerebrum.md
    cortices/
      <cortex-config>.md

This format follows the same readability pattern used by Agent Skills:

1. YAML frontmatter for machine-readable fields.
2. Markdown body for human and LLM context.

Case policy for markdown config keys:

1. Markdown keys must be kebab-case.
2. Snake_case markdown keys are invalid and should fail validation.
3. Snake_case inside values is allowed (for example Python module paths, symbol names, and metadata payload values).

cerebrum.md required fields

Field	Required	Notes
kind	yes	Must be cerebrum.
name	yes	Human-readable bundle name.
description	yes	What this bundle is for and when to use it.
version	yes	Bundle version tag, such as v0.
domain-id	yes	Must match the domain folder name.
tenant-id	yes	Tenant scope used by runtime state.
lifecycle	yes	Current state label such as proposed or active.
required-cortices	yes	List of cortex refs. Each item must include id and source.
degradable-cortices	yes	Explicit list of tolerated-loss cortices, even when empty.

Example:

---
kind: cerebrum
name: demo-cerebrum
description: Single-cortex MVP Domain Bundle for local CLI chat validation.
version: v0
domain-id: demo
tenant-id: tenant-demo
lifecycle: proposed
required-cortices:
  - id: comm.cli
    source: ./cortices/cli-comms-cortex.md
degradable-cortices: []
---

Cortex config required fields

Field	Required	Notes
kind	yes	Must be cortex.
id	yes	Cortex identifier, must match the ref in cerebrum.md.
role	yes	Runtime role such as communication.
profile	yes	Profile key used by cdp up --profile and cdp profile use.
description	yes	Short explanation of cortex purpose.
launch.launcher	yes	Backend type, currently inprocess for MVP.
launch.target.module-path	yes	Python module path for factory/launcher symbol.
launch.target.symbol-name	yes	Callable symbol to build the cortex runtime.

Example:

---
kind: cortex
id: comm.cli
role: communication
profile: cli
description: Communication cortex used by cdp chat in the terminal.
launch:
  launcher: inprocess
  target:
    module-path: cdp.comms_cortex
    symbol-name: create_cli_comms_cortex
---

Source reference model

Each cortex entry in required-cortices and degradable-cortices uses a source field.

Current support:

1. Local relative markdown paths.

Designed next:

1. Remote URL or repository references.
2. Mixed local and remote cortex bundles in one cerebrum.