From 2744a27e7d6b671a2ea2cec7142a2819a81095f6 Mon Sep 17 00:00:00 2001
From: Thibault Pensec <thibault.pensec@symphony.com>
Date: Thu, 18 Jun 2026 12:52:44 +0200
Subject: [PATCH 1/3] feat: add symphony-bdk-cli module
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduces a new `symphony-bdk-cli` Gradle module — a command-line interface built on top of symphony-bdk-core using picocli. Provides sub-commands for health checks, datafeed monitoring, message operations, stream management, and user lookups. Includes design docs, OpenSpec change artifacts, and documentation updates.
---
 .claude/commands/opsx/apply.md                | 152 +++++++++
 .claude/commands/opsx/archive.md              | 157 ++++++++++
 .claude/commands/opsx/explore.md              | 173 +++++++++++
 .claude/commands/opsx/propose.md              | 106 +++++++
 .claude/skills/openspec-apply-change/SKILL.md | 156 ++++++++++
 .../skills/openspec-archive-change/SKILL.md   | 114 +++++++
 .claude/skills/openspec-explore/SKILL.md      | 288 ++++++++++++++++++
 .claude/skills/openspec-propose/SKILL.md      | 110 +++++++
 README.md                                     |  15 +
 docs/cli.md                                   | 160 ++++++++++
 docs/index.md                                 |  44 +--
 gradle/wrapper/gradle-wrapper.properties      |   2 +-
 openspec/changes/add-bdk-cli/.openspec.yaml   |   2 +
 openspec/changes/add-bdk-cli/design.md        |  96 ++++++
 openspec/changes/add-bdk-cli/proposal.md      |  55 ++++
 .../changes/add-bdk-cli/specs/cli/spec.md     | 151 +++++++++
 openspec/changes/add-bdk-cli/tasks.md         |  36 +++
 openspec/config.yaml                          |  20 ++
 settings.gradle                               |   3 +
 symphony-bdk-bom/build.gradle                 |   2 +
 symphony-bdk-cli/README.md                    |  24 ++
 symphony-bdk-cli/build.gradle                 |  46 +++
 .../java/com/symphony/bdk/cli/BdkCli.java     | 136 +++++++++
 .../symphony/bdk/cli/command/BaseCommand.java |  44 +++
 .../bdk/cli/command/ContainerCommand.java     |  19 ++
 .../bdk/cli/command/WhoamiCommand.java        |  17 ++
 .../cli/command/datafeed/DatafeedCommand.java |  15 +
 .../command/datafeed/DatafeedReadCommand.java |  87 ++++++
 .../command/health/HealthCheckCommand.java    |  17 ++
 .../bdk/cli/command/health/HealthCommand.java |  15 +
 .../cli/command/message/MessageCommand.java   |  17 ++
 .../command/message/MessageGetCommand.java    |  27 ++
 .../command/message/MessageListCommand.java   |  49 +++
 .../command/message/MessageSendCommand.java   |  29 ++
 .../bdk/cli/command/stream/StreamCommand.java |  17 ++
 .../cli/command/stream/StreamGetCommand.java  |  27 ++
 .../cli/command/stream/StreamListCommand.java |  25 ++
 .../command/stream/StreamMembersCommand.java  |  21 ++
 .../bdk/cli/command/user/UserCommand.java     |  16 +
 .../bdk/cli/command/user/UserGetCommand.java  |  51 ++++
 .../cli/command/user/UserSearchCommand.java   |  34 +++
 .../BdkCliExecutionExceptionHandler.java      |  73 +++++
 .../bdk/cli/internal/DurationConverter.java   |  50 +++
 .../com/symphony/bdk/cli/internal/Json.java   |  50 +++
 .../bdk/cli/internal/NotFoundException.java   |  17 ++
 .../src/main/resources/logback.xml            |  31 ++
 .../symphony/bdk/cli/BdkCliWiringTest.java    |  54 ++++
 .../com/symphony/bdk/cli/CliTestBase.java     |  40 +++
 .../com/symphony/bdk/cli/CommandTest.java     | 181 +++++++++++
 .../symphony/bdk/cli/DatafeedReadTest.java    |  49 +++
 .../com/symphony/bdk/cli/ExitCodeTest.java    | 115 +++++++
 .../com/symphony/bdk/cli/JsonOutputTest.java  |  65 ++++
 .../bdk/core/config/BdkConfigParser.java      |   2 +-
 53 files changed, 3280 insertions(+), 22 deletions(-)
 create mode 100644 .claude/commands/opsx/apply.md
 create mode 100644 .claude/commands/opsx/archive.md
 create mode 100644 .claude/commands/opsx/explore.md
 create mode 100644 .claude/commands/opsx/propose.md
 create mode 100644 .claude/skills/openspec-apply-change/SKILL.md
 create mode 100644 .claude/skills/openspec-archive-change/SKILL.md
 create mode 100644 .claude/skills/openspec-explore/SKILL.md
 create mode 100644 .claude/skills/openspec-propose/SKILL.md
 create mode 100644 docs/cli.md
 create mode 100644 openspec/changes/add-bdk-cli/.openspec.yaml
 create mode 100644 openspec/changes/add-bdk-cli/design.md
 create mode 100644 openspec/changes/add-bdk-cli/proposal.md
 create mode 100644 openspec/changes/add-bdk-cli/specs/cli/spec.md
 create mode 100644 openspec/changes/add-bdk-cli/tasks.md
 create mode 100644 openspec/config.yaml
 create mode 100644 symphony-bdk-cli/README.md
 create mode 100644 symphony-bdk-cli/build.gradle
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/BdkCli.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/BaseCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/ContainerCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/WhoamiCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/datafeed/DatafeedCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/datafeed/DatafeedReadCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/health/HealthCheckCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/health/HealthCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageGetCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageListCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageSendCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamGetCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamListCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamMembersCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserGetCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserSearchCommand.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/BdkCliExecutionExceptionHandler.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/DurationConverter.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/Json.java
 create mode 100644 symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/NotFoundException.java
 create mode 100644 symphony-bdk-cli/src/main/resources/logback.xml
 create mode 100644 symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/BdkCliWiringTest.java
 create mode 100644 symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/CliTestBase.java
 create mode 100644 symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/CommandTest.java
 create mode 100644 symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/DatafeedReadTest.java
 create mode 100644 symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/ExitCodeTest.java
 create mode 100644 symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/JsonOutputTest.java

diff --git a/.claude/commands/opsx/apply.md b/.claude/commands/opsx/apply.md
new file mode 100644
index 000000000..ae14f0f5f
--- /dev/null
+++ b/.claude/commands/opsx/apply.md
@@ -0,0 +1,152 @@
+---
+name: "OPSX: Apply"
+description: Implement tasks from an OpenSpec change (Experimental)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx:archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.claude/commands/opsx/archive.md b/.claude/commands/opsx/archive.md
new file mode 100644
index 000000000..5e916083a
--- /dev/null
+++ b/.claude/commands/opsx/archive.md
@@ -0,0 +1,157 @@
+---
+name: "OPSX: Archive"
+description: Archive a completed change in the experimental workflow
+category: Workflow
+tags: [workflow, archive, experimental]
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.claude/commands/opsx/explore.md b/.claude/commands/opsx/explore.md
new file mode 100644
index 000000000..1757907e5
--- /dev/null
+++ b/.claude/commands/opsx/explore.md
@@ -0,0 +1,173 @@
+---
+name: "OPSX: Explore"
+description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
+category: Workflow
+tags: [workflow, explore, experimental, thinking]
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.claude/commands/opsx/propose.md b/.claude/commands/opsx/propose.md
new file mode 100644
index 000000000..05276f4d0
--- /dev/null
+++ b/.claude/commands/opsx/propose.md
@@ -0,0 +1,106 @@
+---
+name: "OPSX: Propose"
+description: Propose a new change - create it and generate all artifacts in one step
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.claude/skills/openspec-apply-change/SKILL.md b/.claude/skills/openspec-apply-change/SKILL.md
new file mode 100644
index 000000000..70fbdb856
--- /dev/null
+++ b/.claude/skills/openspec-apply-change/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.claude/skills/openspec-archive-change/SKILL.md b/.claude/skills/openspec-archive-change/SKILL.md
new file mode 100644
index 000000000..12e2f70e9
--- /dev/null
+++ b/.claude/skills/openspec-archive-change/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.claude/skills/openspec-explore/SKILL.md b/.claude/skills/openspec-explore/SKILL.md
new file mode 100644
index 000000000..6858d3f69
--- /dev/null
+++ b/.claude/skills/openspec-explore/SKILL.md
@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │          CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.claude/skills/openspec-propose/SKILL.md b/.claude/skills/openspec-propose/SKILL.md
new file mode 100644
index 000000000..4b7e20418
--- /dev/null
+++ b/.claude/skills/openspec-propose/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/README.md b/README.md
index 5162ec295..8385591da 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,21 @@ public class BotApplication {
 }
 ```
 
+## Command-Line Interface
+The [`symphony-bdk-cli`](./symphony-bdk-cli) module provides an operational `bdk` command-line
+interface that authenticates as a configured bot and performs one-shot Symphony operations
+(messaging, streams, users, datafeed, health) straight from the shell, emitting JSON on `stdout`
+for easy scripting and agent consumption.
+
+```bash
+./gradlew :symphony-bdk-cli:installDist
+ln -s "$(pwd)/symphony-bdk-cli/build/install/symphony-bdk-cli/bin/bdk" /usr/local/bin/bdk
+bdk whoami
+```
+
+See the [CLI documentation](./docs/cli.md) for the full command reference and the JSON / exit-code
+contract.
+
 ## Build from Source
 The Symphony BDK uses a [Gradle](https://docs.gradle.org/) build. The instructions below use the [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html)
 from the root of the source tree. The wrapper script serves as a cross-platform, self-contained bootstrap mechanism for
diff --git a/docs/cli.md b/docs/cli.md
new file mode 100644
index 000000000..468a2eab2
--- /dev/null
+++ b/docs/cli.md
@@ -0,0 +1,160 @@
+# Symphony BDK Command-Line Interface (`bdk`)
+
+The `symphony-bdk-cli` module provides an operational command-line interface that authenticates
+**as a configured bot** and performs one-shot Symphony operations (messaging, streams, users,
+datafeed, health) from the shell.
+
+It is designed to be consumed by both humans and agents (such as Claude Code): **results are
+emitted as JSON on `stdout`**, all logging is routed to `stderr`, and failures map to **stable,
+documented exit codes**.
+
+> **v1 scope.** JSON is the only output format. There is no `--human` table mode, no interactive
+> shell, no project scaffolding, and no OBO (on-behalf-of) support — the CLI always acts as the
+> configured bot. Each invocation performs a fresh authentication.
+
+## Install
+
+The CLI is distributed via the Gradle `application` plugin.
+
+```bash
+# build the distribution
+./gradlew :symphony-bdk-cli:installDist
+
+# the launcher and its runtime jars are produced under:
+#   symphony-bdk-cli/build/install/symphony-bdk-cli/bin/bdk
+#   symphony-bdk-cli/build/install/symphony-bdk-cli/lib/
+
+# put `bdk` on your PATH (symlink the launcher)
+ln -s "$(pwd)/symphony-bdk-cli/build/install/symphony-bdk-cli/bin/bdk" /usr/local/bin/bdk
+
+# verify
+bdk --help
+```
+
+On Windows a `bdk.bat` launcher is produced alongside `bdk`.
+
+## Configuration
+
+The CLI loads a standard BDK configuration file (the same `bdk-config.yaml` used by a bot
+application) via `BdkConfigLoader`.
+
+| Source | Location |
+|--------|----------|
+| Default | `~/.symphony/config.yaml` |
+| Override | `-c` / `--config <path>` (global option) |
+
+```bash
+bdk whoami                              # uses ~/.symphony/config.yaml
+bdk -c /etc/mybot/config.yaml whoami    # explicit config
+```
+
+If the configuration file is missing or cannot be parsed, the CLI prints a JSON error to `stderr`
+and exits non-zero **without contacting Symphony**.
+
+### Global options
+
+| Option | Description |
+|--------|-------------|
+| `-c`, `--config <path>` | Path to the `bdk-config.yaml` (default: `~/.symphony/config.yaml`). |
+| `-v`, `--verbose` | Raise the log level on `stderr` from `WARN` to `DEBUG`. |
+| `-h`, `--help` | Show usage. |
+| `-V`, `--version` | Print the BDK version. |
+
+## Output & exit-code contract
+
+- **Success** → the command result is serialised as a JSON document on `stdout` (pretty-printed);
+  nothing else is written to `stdout`.
+- **Logging** → all BDK / dependency log output goes to `stderr`, keeping `stdout` parseable.
+- **Failure** → a JSON object `{ "error": "<message>", "type": "<exception>" }` is written to
+  `stderr`, and the process exits with a documented code.
+
+| Exit | Meaning |
+|------|---------|
+| `0` | success |
+| `1` | generic / unexpected error |
+| `2` | authentication failure |
+| `3` | not found (resource does not exist / API `404`) |
+| `64` | usage error (bad arguments) |
+
+A caller that captures only `stdout` will see nothing on failure and should branch on the exit
+code (and read `stderr` for the error detail).
+
+## Command reference
+
+### `bdk whoami`
+
+Print the authenticated bot's session identity (a connectivity smoke test).
+
+```bash
+bdk whoami
+```
+
+### `bdk message`
+
+| Command | Description |
+|---------|-------------|
+| `bdk message send <streamId> --message "<text>"` | Send a message to a stream; prints the resulting message. |
+| `bdk message get <messageId>` | Retrieve a single message by id (`3` if it does not exist). |
+| `bdk message list <streamId> [--since <ts>] [--limit N] [--skip N]` | List messages in a stream as a JSON array. `--since` accepts epoch millis or an ISO-8601 instant; it defaults to the last 24 hours. |
+
+```bash
+bdk message send abc123StreamId --message "<messageML>Hello</messageML>"
+bdk message get  abcMessageId
+bdk message list abc123StreamId --since 2026-06-01T00:00:00Z --limit 20
+```
+
+### `bdk stream`
+
+| Command | Description |
+|---------|-------------|
+| `bdk stream list [--limit N] [--skip N]` | List the streams the bot is a member of (JSON array). |
+| `bdk stream members <streamId>` | List the members of a stream. |
+| `bdk stream get <streamId>` | Get a stream's details (`3` if it does not exist). |
+
+### `bdk user`
+
+| Command | Description |
+|---------|-------------|
+| `bdk user get <emailOrId>` | Look up a user. A numeric argument is treated as a user id; an email-shaped argument is treated as an email address (`3` if no such user, `64` if the argument is neither). |
+| `bdk user search <query> [--local] [--limit N] [--skip N]` | Search users by free text (JSON array). |
+
+```bash
+bdk user get 71811853189212
+bdk user get alice@example.com
+bdk user search "alice"
+```
+
+### `bdk datafeed read`
+
+Stream real-time events as **JSON Lines (NDJSON)** — one JSON object per event, per line, on
+`stdout`. The loop stops cleanly after a bound or on `SIGINT` (Ctrl-C).
+
+| Option | Description |
+|--------|-------------|
+| `--count <N>` | Stop after `N` events. |
+| `--timeout <duration>` | Stop after a duration, e.g. `30s`, `5m`, `1h` (ISO-8601 also accepted). |
+
+```bash
+bdk datafeed read --count 10
+bdk datafeed read --timeout 30s | jq 'select(.type == "MESSAGESENT")'
+```
+
+### `bdk health check`
+
+Report the health of the agent and its connected Symphony components.
+
+```bash
+bdk health check
+```
+
+## Examples for scripting / agents
+
+```bash
+# get the bot user id
+bot_id=$(bdk whoami | jq -r '.id')
+
+# fail fast on auth errors
+if ! bdk health check >/dev/null 2>err.json; then
+  echo "health check failed (exit $?): $(jq -r '.error' err.json)" >&2
+fi
+```
diff --git a/docs/index.md b/docs/index.md
index f404d8c6d..8bd9a5b84 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -27,31 +27,35 @@ If you are just getting started with Symphony Bot developments, you may want to
 
 The reference documentation consists of the following sections:
 
-| Section                                  | Description                                                           |
-|------------------------------------------|:---------------------------------------------------------------------:|
-| [Getting Started](./getting-started.html)  | Introducing Symphony BDK for beginners                                |
-| [Migration Guide](./migration.html)        | Guide to migrate to Symphony BDK 2.0                                  |
-| [Configuration](./configuration.html)      | Configuration structure, formats, how to load from code               |
-| [Authentication](./authentication.html)    | RSA or certificate authentication, OBO, extension app authentication  |
-| [Datafeed Loop](datafeed.html)             | Receiving real time events                                            |
-| [Fluent API](fluent-api.html)              | Java Fluent API usage                                                 |
-| [Message API](message.html)                | Sending or searching messages, usage of templates                     |
-| [Stream API](stream.html)                  | Create and manage streams                                             |
-| [User API](user.html)                      | Manage users                                                          |
-| [Presence API](presence.html)              | Manage user presence status                                           |
-| [Application API](application.html)        | Managing applications                                                 |
-| [Signal API](signal.html)                  | Creating and managing signals                                         |
-| [Connection API](connection.html)          | Managing connections                                                  |
-| [Disclaimer API](disclaimer.html)          | Managing disclaimers                                                  |
-| [Health API](health.html)                  | Get health check status                                               |
-| [Activity API](activity-api.html)          | The Activity Registry, creating custom activities                     |
-| [Extending the BDK](extension.html)        | How to use or develop BDK extensions                                  |
-| [Integration Test](test.html)              | How to write the integration tests for Symphony BDK Bot application   |
+| Section                                   | Description                                                           |
+|-------------------------------------------|:---------------------------------------------------------------------:|
+| [Getting Started](./getting-started.html) | Introducing Symphony BDK for beginners                                |
+| [Migration Guide](./migration.html)       | Guide to migrate to Symphony BDK 2.0                                  |
+| [Configuration](./configuration.html)     | Configuration structure, formats, how to load from code               |
+| [Authentication](./authentication.html)   | RSA or certificate authentication, OBO, extension app authentication  |
+| [Datafeed Loop](datafeed.html)            | Receiving real time events                                            |
+| [Fluent API](fluent-api.html)             | Java Fluent API usage                                                 |
+| [Message API](message.html)               | Sending or searching messages, usage of templates                     |
+| [Stream API](stream.html)                 | Create and manage streams                                             |
+| [User API](user.html)                     | Manage users                                                          |
+| [Presence API](presence.html)             | Manage user presence status                                           |
+| [Application API](application.html)       | Managing applications                                                 |
+| [Signal API](signal.html)                 | Creating and managing signals                                         |
+| [Connection API](connection.html)         | Managing connections                                                  |
+| [Disclaimer API](disclaimer.html)         | Managing disclaimers                                                  |
+| [Health API](health.html)                 | Get health check status                                               |
+| [Activity API](activity-api.html)         | The Activity Registry, creating custom activities                     |
+| [Extending the BDK](extension.html)       | How to use or develop BDK extensions                                  |
+| [Integration Test](test.html)             | How to write the integration tests for Symphony BDK Bot application   |
 
 ### Spring Boot
 Getting Started guides are also available for Spring Boot:
 - [Core Starter](./spring-boot/core-starter.html)
 - [App Starter](./spring-boot/app-starter.html)
 
+### CLI
+A command-line interface is also available to interact with Symphony directly from the terminal:
+- [BDK CLI](./cli.html)
+
 ### Technical Documentation
 You can find an overview of the BDK Architecture [here](./tech/architecture.html).
diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties
index 3499ded5c..7a04a2dcf 100644
--- a/gradle/wrapper/gradle-wrapper.properties
+++ b/gradle/wrapper/gradle-wrapper.properties
@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.5-bin.zip
 networkTimeout=10000
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
diff --git a/openspec/changes/add-bdk-cli/.openspec.yaml b/openspec/changes/add-bdk-cli/.openspec.yaml
new file mode 100644
index 000000000..3ac681e39
--- /dev/null
+++ b/openspec/changes/add-bdk-cli/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-17
diff --git a/openspec/changes/add-bdk-cli/design.md b/openspec/changes/add-bdk-cli/design.md
new file mode 100644
index 000000000..3d4a5b93c
--- /dev/null
+++ b/openspec/changes/add-bdk-cli/design.md
@@ -0,0 +1,96 @@
+## Context
+
+The BDK is a multi-module Gradle build (Java 17, Spring Boot 3). The user-facing entry point
+is the `SymphonyBdk` facade, built from a `BdkConfig` that `BdkConfigLoader` can read from a
+file or from the `~/.symphony` directory. Services are exposed as accessors on the facade:
+`messages()`, `streams()`, `users()`, `datafeed()`, `health()`, `sessions()`.
+
+The internal `tibot` CLI (a *standalone Maven consumer* of the published BDK) already proves a
+clean pattern we want to adopt: a picocli root command with global `-c/--config` and `--json`
+options, noun commands as containers, verb commands as `Runnable` leaves reaching the root via
+`@ParentCommand`, each building a fresh `SymphonyBdk` and printing a result. This change brings
+that pattern **in-tree** as a first-class module so it tracks BDK `HEAD` and ships with the
+project.
+
+## Goals / Non-Goals
+
+**Goals:**
+- A `symphony-bdk-cli` module producing an installable `bdk` launcher (`installDist`).
+- One-shot operational commands covering messaging, streams, users, datafeed and health.
+- Output that is trivially consumable by an agent (Claude Code): JSON on `stdout`, clean of
+  log noise; meaningful exit codes; JSON errors on `stderr`.
+- Reuse the public `SymphonyBdk` facade only — no new core APIs.
+
+**Non-Goals:**
+- A `--human` / table output mode (reserved for a later change; v1 is JSON-only to keep the code small).
+- A long-running interactive shell, REPL, or daemon.
+- Project scaffolding / `bdk init` (overlaps with the existing `generator-symphony`; out of scope).
+- Session caching / credential persistence across invocations (see Risks).
+- GraalVM native-image packaging (the BDK stack is reflection-heavy; fat-jar/installDist is the v1 target).
+- OBO (on-behalf-of) flows — v1 acts strictly as the configured bot.
+
+## Decisions
+
+### 1. picocli, git-style noun→verb tree (mirror tibot)
+Root `BdkCli implements Runnable` with `@Command(subcommands = {...}, mixinStandardHelpOptions = true)`.
+Noun commands (`message`, `stream`, `user`, `datafeed`, `health`) are containers; verb commands are
+`Runnable` leaves. Leaves obtain shared config via the `@ParentCommand` chain. `main()` does
+`System.exit(new CommandLine(new BdkCli()).execute(args))`.
+
+### 2. Configuration resolution
+Global `-c/--config <path>` with default `${user.home}/.symphony/config.yaml`, loaded via
+`BdkConfigLoader.loadFromFile(...)`. The resolved `BdkConfig` is used to build one `SymphonyBdk`
+per invocation. The CLI acts **as the bot** — there is no separate human identity in v1.
+
+### 3. JSON-only output on a clean stdout (v1)
+There is no `--human` flag in v1; every command serialises its result to JSON via a shared
+Jackson `ObjectMapper` and writes it to `stdout`. To keep `stdout` parseable, a CLI-specific
+`logback.xml` routes **all** logging to `stderr` (default level `WARN`, raised by `-v/--verbose`).
+This is the single most important behaviour for the Claude Code use-case.
+
+### 4. Error envelope + exit codes
+A picocli `IExecutionExceptionHandler` serialises any thrown exception to a JSON object
+(`{"error": "<message>", "type": "<exception>"}`) on `stderr` and maps it to an exit code:
+
+| Exit | Meaning |
+|------|---------|
+| 0 | success |
+| 1 | generic / unexpected error |
+| 2 | authentication failure (`AuthInitializationException`, `AuthUnauthorizedException`) |
+| 3 | not found / API 404 (`ApiException`/`ApiRuntimeException` with 404) |
+| 64 | usage error (bad arguments) — set explicitly to the conventional `EX_USAGE` value; picocli's own `ExitCode.USAGE` is `2`, which would otherwise collide with authentication failure |
+
+> Note: the service layer wraps `ApiException` into an unchecked `ApiRuntimeException` (retry
+> decorator), so the handler walks the exception cause chain and inspects both. The invalid-input
+> exit code is set to `64` on every command via `exitCodeOnInvalidInput`, and a `ParameterException`
+> thrown during command execution is also mapped to `64`.
+
+### 5. `datafeed read` emits JSON Lines (NDJSON)
+A single JSON object does not fit a stream of events. `datafeed read` registers a
+`RealTimeEventListener`, starts the loop, and prints **one JSON object per event per line** to
+`stdout`. It stops after `--count N` events, after `--timeout <duration>`, or on SIGINT — then
+cleanly stops the loop. This is the one command whose `stdout` is a stream, not a single document.
+
+### 6. Distribution via the `application` plugin
+Apply the Gradle `application` plugin with `mainClass = com.symphony.bdk.cli.BdkCli`.
+`./gradlew :symphony-bdk-cli:installDist` produces `build/install/symphony-bdk-cli/bin/bdk`
+(launcher) + `lib/` (classpath jars). Users symlink that `bdk` script onto `PATH`. The
+`jersey2` HTTP implementation and a logging backend are added as `runtimeOnly` so the
+distribution is self-contained.
+
+## Risks / Trade-offs
+
+- **Re-authentication per invocation.** Each command builds a fresh `SymphonyBdk`, triggering a
+  full RSA→JWT login (and KM token) round-trip. Fine for occasional human use; for an agent
+  firing many calls in sequence this adds latency. Accepted for v1 (keeps the CLI stateless and
+  simple); a session cache or background daemon is a future enhancement.
+- **JSON-only.** Humans lose pretty tables in v1. Mitigated by pretty-printing JSON and the
+  planned `--human` follow-up.
+- **stdout/stderr split for errors.** Errors go to `stderr`, results to `stdout`. A caller that
+  captures only `stdout` sees nothing on failure and must rely on the exit code. We document the
+  exit-code contract; a unified `{ok, data|error}` envelope on stdout was considered but rejected
+  for v1 to keep success-path output a bare result document.
+- **Bundled logback config** could clash if a future consumer embeds the CLI as a library; the CLI
+  is an application, not a library, so this is acceptable.
+- **`datafeed read` lifecycle.** Must guarantee the loop is stopped on `--count`/`--timeout`/SIGINT
+  to avoid a hung process; handled with a shutdown hook and a bounded listener.
diff --git a/openspec/changes/add-bdk-cli/proposal.md b/openspec/changes/add-bdk-cli/proposal.md
new file mode 100644
index 000000000..7cd2acb87
--- /dev/null
+++ b/openspec/changes/add-bdk-cli/proposal.md
@@ -0,0 +1,55 @@
+## Why
+
+The Symphony BDK for Java has no command-line interface. Every interaction with
+Symphony today requires writing, compiling and running Java code (`new SymphonyBdk(...)`,
+register activities, `datafeed().start()`). There is no way to quickly send a message,
+inspect a stream, look up a user, or smoke-test a bot's credentials from a terminal —
+let alone to drive those operations from an agent such as Claude Code.
+
+An operational CLI closes that gap: a human (or an agent on their behalf) authenticates
+**as the bot** using an existing `bdk-config.yaml` and performs one-shot Symphony
+operations from the shell. Because a primary caller will be Claude Code, machine-readable
+output is the default rather than an afterthought.
+
+## What Changes
+
+- Add a new Gradle module **`symphony-bdk-cli`** containing a [picocli](https://picocli.info/)
+  "git-style" noun→verb command tree, mirroring the proven structure of the internal
+  `tibot` CLI.
+- The CLI loads a `BdkConfig` from `~/.symphony/config.yaml` by default, overridable with
+  `-c/--config <path>`, and instantiates a `SymphonyBdk` to act **as the configured bot**.
+- **JSON is the only output format in v1** — emitted on `stdout`. All BDK/logback logging is
+  redirected to `stderr` so `stdout` stays parseable. (A `--human` table mode is reserved as a
+  future enhancement.)
+- Errors are emitted as JSON on `stderr` with **stable, documented exit codes** so callers can
+  branch without parsing text.
+- Distribution via the Gradle `application` plugin: `installDist` produces a `bin/bdk`
+  launcher that can be symlinked onto `PATH`, enabling `bdk <noun> <verb> …`.
+- v1 command surface:
+  - `bdk whoami` — print the authenticated bot's session/identity (connectivity smoke test)
+  - `bdk message send|get|list`
+  - `bdk stream list|members|get`
+  - `bdk user get|search`
+  - `bdk datafeed read` — stream real-time events as JSON Lines
+  - `bdk health check`
+
+## Capabilities
+
+### New Capabilities
+- `cli`: An operational command-line interface that authenticates as a configured bot and
+  performs one-shot Symphony operations (messaging, streams, users, datafeed, health) with
+  JSON output suitable for scripting and agent consumption.
+
+### Modified Capabilities
+<!-- None. This change is purely additive and does not alter the behaviour of any existing core capability. -->
+
+## Impact
+
+- **New module**: `symphony-bdk-cli` (added to `settings.gradle`).
+- **Build**: applies `bdk.java-common-conventions` (Java 17) + the Gradle `application` and
+  `shadow`/distribution plumbing; depends on `project(':symphony-bdk-core')` and, at runtime,
+  `project(':symphony-bdk-http:symphony-bdk-http-jersey2')`.
+- **New runtime dependency**: `info.picocli:picocli` (must be added to `symphony-bdk-bom`).
+- **No changes to existing modules' behaviour** — the CLI is a consumer of the public
+  `SymphonyBdk` facade only.
+- **Docs**: a new `docs/cli.md` and a `bin/bdk` install note.
diff --git a/openspec/changes/add-bdk-cli/specs/cli/spec.md b/openspec/changes/add-bdk-cli/specs/cli/spec.md
new file mode 100644
index 000000000..a06636eb7
--- /dev/null
+++ b/openspec/changes/add-bdk-cli/specs/cli/spec.md
@@ -0,0 +1,151 @@
+## ADDED Requirements
+
+### Requirement: CLI module and installable launcher
+The system SHALL provide a `symphony-bdk-cli` Gradle module that builds an installable `bdk`
+launcher via the Gradle `application` plugin's `installDist` task, with main class
+`com.symphony.bdk.cli.BdkCli`.
+
+#### Scenario: Building the distribution
+- **WHEN** a developer runs `./gradlew :symphony-bdk-cli:installDist`
+- **THEN** a runnable launcher is produced at `build/install/symphony-bdk-cli/bin/bdk` together
+  with all required runtime jars under `lib/`
+
+#### Scenario: Invoking on PATH
+- **WHEN** the `bdk` launcher is symlinked onto `PATH` and invoked as `bdk <noun> <verb> [args]`
+- **THEN** the corresponding command executes and the process exits with a documented exit code
+
+#### Scenario: No subcommand prints usage
+- **WHEN** `bdk` is invoked with no arguments
+- **THEN** the root usage/help is printed and the process exits without performing any Symphony call
+
+### Requirement: Configuration resolution
+The CLI SHALL load a `BdkConfig` from `~/.symphony/config.yaml` by default and SHALL accept a
+`-c`/`--config <path>` global option to override the location, using `BdkConfigLoader`.
+
+#### Scenario: Default configuration location
+- **WHEN** a command is run with no `--config` option and `~/.symphony/config.yaml` exists
+- **THEN** the CLI loads that file and authenticates the configured bot
+
+#### Scenario: Explicit configuration override
+- **WHEN** a command is run with `--config /path/to/other.yaml`
+- **THEN** the CLI loads the specified file instead of the default
+
+#### Scenario: Missing configuration
+- **WHEN** the resolved configuration file does not exist or cannot be parsed
+- **THEN** the CLI prints a JSON error to `stderr` and exits with a non-zero code without contacting Symphony
+
+### Requirement: Authentication as the configured bot
+The CLI SHALL authenticate as the bot described by the loaded configuration and SHALL perform all
+operations using that bot's session.
+
+#### Scenario: Successful authentication
+- **WHEN** a command is run with a configuration containing valid bot credentials
+- **THEN** the CLI authenticates the bot and performs the requested operation as that bot
+
+#### Scenario: Authentication failure
+- **WHEN** the bot credentials are invalid or authentication is rejected
+- **THEN** the CLI prints a JSON error to `stderr` and exits with code `2`
+
+### Requirement: JSON output on standard output
+In v1 the CLI SHALL emit command results as JSON on `stdout` and SHALL NOT provide any other
+output format.
+
+#### Scenario: Result serialised as JSON
+- **WHEN** a command completes successfully
+- **THEN** its result is written to `stdout` as a JSON document and nothing else is written to `stdout`
+
+#### Scenario: Logging does not pollute stdout
+- **WHEN** the BDK or its dependencies emit log output during a command
+- **THEN** that log output is written to `stderr`, leaving `stdout` as parseable JSON
+
+### Requirement: Error reporting and exit codes
+The CLI SHALL report errors as JSON on `stderr` and SHALL use stable, documented exit codes so
+that callers can branch on outcome without parsing text.
+
+#### Scenario: Error emitted as JSON
+- **WHEN** a command fails
+- **THEN** a JSON object containing at least an `error` message is written to `stderr`
+
+#### Scenario: Documented exit codes
+- **WHEN** a command fails due to authentication, the exit code is `2`; due to a not-found resource, `3`;
+  due to invalid arguments, `64`; for any other error, `1`
+- **THEN** the process terminates with the corresponding code, while success terminates with `0`
+
+### Requirement: `whoami` command
+The CLI SHALL provide a `bdk whoami` command that prints the authenticated bot's session identity.
+
+#### Scenario: Print bot identity
+- **WHEN** `bdk whoami` is run with a valid configuration
+- **THEN** the bot's session details (such as user id and display name from `sessions()`) are printed as JSON on `stdout`
+
+### Requirement: Message commands
+The CLI SHALL provide `bdk message send`, `bdk message get` and `bdk message list` commands backed
+by the BDK `MessageService`.
+
+#### Scenario: Send a message
+- **WHEN** `bdk message send <streamId> --message "<text>"` is run
+- **THEN** the message is sent to the stream and the resulting message id is printed as JSON
+
+#### Scenario: Get a message by id
+- **WHEN** `bdk message get <messageId>` is run
+- **THEN** the message is retrieved and printed as JSON, or exit code `3` is returned if it does not exist
+
+#### Scenario: List messages in a stream
+- **WHEN** `bdk message list <streamId>` is run, optionally with a `--since` timestamp
+- **THEN** the matching messages are printed as a JSON array
+
+### Requirement: Stream commands
+The CLI SHALL provide `bdk stream list`, `bdk stream members` and `bdk stream get` commands backed
+by the BDK `StreamService`.
+
+#### Scenario: List the bot's streams
+- **WHEN** `bdk stream list` is run
+- **THEN** the streams the bot is a member of are printed as a JSON array
+
+#### Scenario: List stream members
+- **WHEN** `bdk stream members <streamId>` is run
+- **THEN** the members of the stream are printed as a JSON array
+
+#### Scenario: Get stream details
+- **WHEN** `bdk stream get <streamId>` is run
+- **THEN** the stream's details are printed as JSON, or exit code `3` is returned if it does not exist
+
+### Requirement: User commands
+The CLI SHALL provide `bdk user get` and `bdk user search` commands backed by the BDK `UserService`.
+`bdk user get` SHALL accept a single positional argument and detect by pattern whether it is an
+email address or a numeric user id, looking the user up accordingly.
+
+#### Scenario: Get a user by id
+- **WHEN** `bdk user get <argument>` is run and the argument matches a numeric user id pattern
+- **THEN** the user is looked up by id and printed as JSON, or exit code `3` is returned if no such user exists
+
+#### Scenario: Get a user by email
+- **WHEN** `bdk user get <argument>` is run and the argument matches an email-address pattern
+- **THEN** the user is looked up by email and printed as JSON, or exit code `3` is returned if no such user exists
+
+#### Scenario: Search users
+- **WHEN** `bdk user search <query>` is run
+- **THEN** the matching users are printed as a JSON array
+
+### Requirement: Datafeed read command
+The CLI SHALL provide a `bdk datafeed read` command that streams real-time events as JSON Lines and
+terminates cleanly on a bound or interruption.
+
+#### Scenario: Stream events as JSON Lines
+- **WHEN** `bdk datafeed read` is run
+- **THEN** each received real-time event is printed as a single JSON object on its own line on `stdout`
+
+#### Scenario: Bounded read
+- **WHEN** `bdk datafeed read --count <N>` or `--timeout <duration>` is run
+- **THEN** the command stops the datafeed loop and exits with code `0` after the bound is reached
+
+#### Scenario: Interrupted read
+- **WHEN** the process receives SIGINT while reading
+- **THEN** the datafeed loop is stopped cleanly before the process exits
+
+### Requirement: Health check command
+The CLI SHALL provide a `bdk health check` command backed by the BDK `HealthService`.
+
+#### Scenario: Report health
+- **WHEN** `bdk health check` is run
+- **THEN** the health status of the bot's connected Symphony components is printed as JSON
diff --git a/openspec/changes/add-bdk-cli/tasks.md b/openspec/changes/add-bdk-cli/tasks.md
new file mode 100644
index 000000000..80115cd88
--- /dev/null
+++ b/openspec/changes/add-bdk-cli/tasks.md
@@ -0,0 +1,36 @@
+## 1. Module bootstrap & build
+
+- [x] 1.1 Add `info.picocli:picocli` version constraint to `symphony-bdk-bom`
+- [x] 1.2 Create `symphony-bdk-cli` module and register it in `settings.gradle`
+- [x] 1.3 Apply `bdk.java-common-conventions`, the `application` plugin (`mainClass = com.symphony.bdk.cli.BdkCli`, `applicationName = 'bdk'` so `installDist` emits `bin/bdk`), and depend on `project(':symphony-bdk-core')` + runtimeOnly `project(':symphony-bdk-http:symphony-bdk-http-jersey2')` + picocli
+- [x] 1.4 Add a CLI-specific `logback.xml` that routes all logging to `stderr` (default `WARN`)
+- [x] 1.5 Verify `./gradlew :symphony-bdk-cli:installDist` produces `bin/bdk` + `lib/`
+
+## 2. CLI framework & cross-cutting behaviour
+
+- [x] 2.1 Implement root `BdkCli` command: global `-c/--config` (default `~/.symphony/config.yaml`), `-v/--verbose`, `mixinStandardHelpOptions`, `main()` with `System.exit(...execute(args))`
+- [x] 2.2 Implement shared config loading (`BdkConfigLoader.loadFromFile`) and `SymphonyBdk` construction helper reachable by leaf commands
+- [x] 2.3 Implement a shared Jackson `ObjectMapper` JSON writer for results on `stdout`
+- [x] 2.4 Implement `IExecutionExceptionHandler` mapping exceptions to JSON-on-`stderr` + exit codes (0/1/2/3/64)
+
+## 3. Commands
+
+- [x] 3.1 `whoami` — print bot session identity via `sessions()`
+- [x] 3.2 `message` container + `send`, `get`, `list` via `messages()`
+- [x] 3.3 `stream` container + `list`, `members`, `get` via `streams()`
+- [x] 3.4 `user` container + `get` (pattern-detect email vs numeric id), `search` via `users()`
+- [x] 3.5 `datafeed read` — JSON Lines event stream with `--count`/`--timeout`/SIGINT bounds via `datafeed()`
+- [x] 3.6 `health check` via `health()`
+
+## 4. Tests
+
+- [x] 4.1 picocli wiring tests: command/subcommand registration, option parsing, default config path
+- [x] 4.2 Exit-code / error-envelope tests (auth failure → 2, not-found → 3, bad args → 64)
+- [x] 4.3 JSON output tests asserting `stdout` is valid JSON and logs go to `stderr`
+- [x] 4.4 Per-command tests against a mocked `SymphonyBdk` / services
+
+## 5. Distribution & docs
+
+- [x] 5.1 Provide a `bin/bdk` install note (symlink `installDist` launcher onto `PATH`)
+- [x] 5.2 Write `docs/cli.md`: install, configuration, command reference, JSON/exit-code contract
+- [x] 5.3 Update `README.md` to mention the CLI
diff --git a/openspec/config.yaml b/openspec/config.yaml
new file mode 100644
index 000000000..392946c67
--- /dev/null
+++ b/openspec/config.yaml
@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours
diff --git a/settings.gradle b/settings.gradle
index c4e128535..e2ca9493f 100644
--- a/settings.gradle
+++ b/settings.gradle
@@ -6,6 +6,9 @@ include(':symphony-bdk-core')
 include(':symphony-bdk-config')
 include(':symphony-bdk-extension-api')
 
+// command-line interface
+include(':symphony-bdk-cli')
+
 // http client
 include(':symphony-bdk-http:symphony-bdk-http-api')
 include(':symphony-bdk-http:symphony-bdk-http-jersey2')
diff --git a/symphony-bdk-bom/build.gradle b/symphony-bdk-bom/build.gradle
index c2d454eec..185e191a1 100644
--- a/symphony-bdk-bom/build.gradle
+++ b/symphony-bdk-bom/build.gradle
@@ -72,6 +72,8 @@ dependencies {
         api 'com.github.jknack:handlebars:4.5.1'
         api 'org.reflections:reflections:0.10.2'
 
+        api 'info.picocli:picocli:4.7.6'
+
         api 'com.tngtech.archunit:archunit-junit5:1.2.1'
         api 'org.mock-server:mockserver-netty:5.15.0'
         api 'org.assertj:assertj-core:3.27.7'
diff --git a/symphony-bdk-cli/README.md b/symphony-bdk-cli/README.md
new file mode 100644
index 000000000..0f722489a
--- /dev/null
+++ b/symphony-bdk-cli/README.md
@@ -0,0 +1,24 @@
+# symphony-bdk-cli
+
+An operational command-line interface (`bdk`) for the Symphony BDK. It authenticates as a
+configured bot and performs one-shot Symphony operations, emitting JSON on `stdout`.
+
+## Install (`bin/bdk` onto `PATH`)
+
+```bash
+# build the launcher + runtime jars
+./gradlew :symphony-bdk-cli:installDist
+
+# the launcher is produced at:
+#   symphony-bdk-cli/build/install/symphony-bdk-cli/bin/bdk
+
+# symlink it onto your PATH
+ln -s "$(pwd)/symphony-bdk-cli/build/install/symphony-bdk-cli/bin/bdk" /usr/local/bin/bdk
+
+bdk --help
+```
+
+By default the CLI reads `~/.symphony/config.yaml` (override with `-c/--config`).
+
+See [`docs/cli.md`](../docs/cli.md) for the full command reference, configuration and the
+JSON / exit-code contract.
diff --git a/symphony-bdk-cli/build.gradle b/symphony-bdk-cli/build.gradle
new file mode 100644
index 000000000..c965a35e0
--- /dev/null
+++ b/symphony-bdk-cli/build.gradle
@@ -0,0 +1,46 @@
+plugins {
+    id 'bdk.java-common-conventions'
+    id 'application'
+}
+
+description = 'Symphony Java BDK - Command Line Interface'
+
+application {
+    mainClass.set('com.symphony.bdk.cli.BdkCli')
+    // emit `bin/bdk` (and `bin/bdk.bat`) from `installDist` rather than the project name
+    applicationName = 'bdk'
+}
+
+// keep the install directory named after the module (build/install/symphony-bdk-cli/),
+// while the launcher script itself stays `bdk` (driven by applicationName above)
+distributions {
+    main {
+        distributionBaseName = 'symphony-bdk-cli'
+    }
+}
+
+dependencies {
+
+    implementation project(':symphony-bdk-core')
+
+    // self-contained distribution: bundle an HTTP implementation and a logging backend
+    runtimeOnly project(':symphony-bdk-http:symphony-bdk-http-jersey2')
+    runtimeOnly project(':symphony-bdk-template:symphony-bdk-template-freemarker')
+
+    // command-line parsing
+    implementation 'info.picocli:picocli'
+
+    // JSON serialisation of command results
+    implementation 'com.fasterxml.jackson.core:jackson-databind'
+    implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310'
+
+    // logging: routed to stderr by the bundled logback.xml; compiled against so verbosity can be tuned
+    implementation 'ch.qos.logback:logback-classic'
+    implementation 'org.slf4j:slf4j-api'
+
+    testImplementation 'org.junit.jupiter:junit-jupiter'
+    testImplementation 'org.assertj:assertj-core'
+    testImplementation 'org.mockito:mockito-core'
+    testImplementation 'org.mockito:mockito-junit-jupiter'
+    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/BdkCli.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/BdkCli.java
new file mode 100644
index 000000000..b8624c8ad
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/BdkCli.java
@@ -0,0 +1,136 @@
+package com.symphony.bdk.cli;
+
+import com.symphony.bdk.cli.command.WhoamiCommand;
+import com.symphony.bdk.cli.command.datafeed.DatafeedCommand;
+import com.symphony.bdk.cli.command.health.HealthCommand;
+import com.symphony.bdk.cli.command.message.MessageCommand;
+import com.symphony.bdk.cli.command.stream.StreamCommand;
+import com.symphony.bdk.cli.command.user.UserCommand;
+import com.symphony.bdk.cli.internal.BdkCliExecutionExceptionHandler;
+import com.symphony.bdk.core.SymphonyBdk;
+import com.symphony.bdk.core.auth.exception.AuthInitializationException;
+import com.symphony.bdk.core.auth.exception.AuthUnauthorizedException;
+import com.symphony.bdk.core.config.BdkConfigLoader;
+import com.symphony.bdk.core.config.exception.BdkConfigException;
+import com.symphony.bdk.core.config.model.BdkConfig;
+
+import org.slf4j.LoggerFactory;
+import picocli.CommandLine;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Model.CommandSpec;
+import picocli.CommandLine.Option;
+import picocli.CommandLine.Spec;
+
+import java.nio.file.Path;
+
+/**
+ * Root command of the Symphony BDK CLI.
+ *
+ * <p>Loads a {@link BdkConfig} (default {@code ~/.symphony/config.yaml}, overridable with {@code
+ * -c/--config}) and builds a single {@link SymphonyBdk} per invocation, acting as the configured
+ * bot. Results are serialised as JSON on {@code stdout}; all logging is routed to {@code stderr}.
+ */
+@Command(
+    name = "bdk",
+    mixinStandardHelpOptions = true,
+    versionProvider = BdkCli.VersionProvider.class,
+    synopsisSubcommandLabel = "<command>",
+    description = "Operational CLI for the Symphony BDK. Authenticates as the configured bot and "
+        + "performs one-shot Symphony operations, emitting JSON on stdout.",
+    subcommands = {
+        WhoamiCommand.class,
+        MessageCommand.class,
+        StreamCommand.class,
+        UserCommand.class,
+        DatafeedCommand.class,
+        HealthCommand.class
+    })
+public class BdkCli implements Runnable {
+
+  @Spec
+  CommandSpec spec;
+
+  @Option(
+      names = {"-c", "--config"},
+      paramLabel = "<path>",
+      defaultValue = "${sys:user.home}/.symphony/config.yaml",
+      description = "Path to the bdk-config.yaml (default: ${DEFAULT-VALUE}).")
+  Path configPath;
+
+  @Option(
+      names = {"-v", "--verbose"},
+      description = "Raise the log level on stderr (WARN → DEBUG).")
+  boolean verbose;
+
+  /** Lazily-built BDK facade; may be pre-set for testing. */
+  private SymphonyBdk bdk;
+
+  /**
+   * Builds (and caches) the {@link SymphonyBdk} facade for this invocation, authenticating as the
+   * configured bot. Reachable by leaf commands through the parent-command chain.
+   */
+  public SymphonyBdk bdk() throws AuthInitializationException, AuthUnauthorizedException, BdkConfigException {
+    applyVerbosity();
+    if (bdk == null) {
+      final BdkConfig config = BdkConfigLoader.loadFromFile(configPath.toString());
+      bdk = SymphonyBdk.builder().config(config).build();
+    }
+    return bdk;
+  }
+
+  /** Test seam: inject a pre-built (typically mocked) facade, bypassing config loading and auth. */
+  void setBdk(SymphonyBdk bdk) {
+    this.bdk = bdk;
+  }
+
+  /** Writes a command result to {@code stdout} as a pretty-printed JSON document. */
+  public void emit(Object result) {
+    spec.commandLine().getOut().println(com.symphony.bdk.cli.internal.Json.pretty(result));
+    spec.commandLine().getOut().flush();
+  }
+
+  private void applyVerbosity() {
+    if (verbose) {
+      final org.slf4j.Logger root = LoggerFactory.getLogger(org.slf4j.Logger.ROOT_LOGGER_NAME);
+      if (root instanceof ch.qos.logback.classic.Logger) {
+        ((ch.qos.logback.classic.Logger) root).setLevel(ch.qos.logback.classic.Level.DEBUG);
+      }
+    }
+  }
+
+  /** Invoked when no subcommand is supplied: print usage and perform no Symphony call. */
+  @Override
+  public void run() {
+    spec.commandLine().usage(spec.commandLine().getOut());
+  }
+
+  /** Builds a fully-configured {@link CommandLine} (shared by {@link #main(String[])} and tests). */
+  public static CommandLine commandLine(BdkCli app) {
+    final CommandLine cmd = new CommandLine(app)
+        .setExecutionExceptionHandler(new BdkCliExecutionExceptionHandler())
+        .setCaseInsensitiveEnumValuesAllowed(true);
+    applyUsageExitCode(cmd);
+    return cmd;
+  }
+
+  /** Recursively sets the invalid-input exit code on every command (see {@code EXIT_USAGE}). */
+  private static void applyUsageExitCode(CommandLine cmd) {
+    cmd.getCommandSpec().exitCodeOnInvalidInput(BdkCliExecutionExceptionHandler.EXIT_USAGE);
+    for (CommandLine sub : cmd.getSubcommands().values()) {
+      applyUsageExitCode(sub);
+    }
+  }
+
+  public static void main(String[] args) {
+    System.exit(commandLine(new BdkCli()).execute(args));
+  }
+
+  /** Reports the BDK version stamped into the jar manifest by the build. */
+  static class VersionProvider implements CommandLine.IVersionProvider {
+    @Override
+    public String[] getVersion() {
+      final String version = BdkCli.class.getPackage().getImplementationVersion();
+      return new String[] {"bdk " + (version != null ? version : "(development)")};
+    }
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/BaseCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/BaseCommand.java
new file mode 100644
index 000000000..eccb1f00b
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/BaseCommand.java
@@ -0,0 +1,44 @@
+package com.symphony.bdk.cli.command;
+
+import com.symphony.bdk.cli.BdkCli;
+import com.symphony.bdk.core.SymphonyBdk;
+import com.symphony.bdk.core.auth.exception.AuthInitializationException;
+import com.symphony.bdk.core.auth.exception.AuthUnauthorizedException;
+import com.symphony.bdk.core.config.exception.BdkConfigException;
+
+import picocli.CommandLine;
+import picocli.CommandLine.Model.CommandSpec;
+import picocli.CommandLine.Spec;
+
+import java.util.concurrent.Callable;
+
+/**
+ * Base class for leaf (verb) commands. Provides access to the shared {@link SymphonyBdk} facade and
+ * a JSON emitter, both reached on the root {@link BdkCli} command via the parent-command chain.
+ *
+ * <p>Subclasses implement {@link Callable#call()}, returning an exit code (typically {@link
+ * CommandLine.ExitCode#OK}). Any thrown exception is routed to the CLI's execution-exception
+ * handler, which maps it to a JSON error envelope and a documented exit code.
+ */
+public abstract class BaseCommand implements Callable<Integer> {
+
+  @Spec
+  protected CommandSpec spec;
+
+  /** The root command, reached from any depth in the subcommand tree. */
+  protected BdkCli root() {
+    return (BdkCli) spec.root().userObject();
+  }
+
+  /** The shared, lazily-authenticated BDK facade. */
+  protected SymphonyBdk bdk()
+      throws AuthInitializationException, AuthUnauthorizedException, BdkConfigException {
+    return root().bdk();
+  }
+
+  /** Writes {@code result} to {@code stdout} as JSON and returns {@link CommandLine.ExitCode#OK}. */
+  protected int emit(Object result) {
+    root().emit(result);
+    return CommandLine.ExitCode.OK;
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/ContainerCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/ContainerCommand.java
new file mode 100644
index 000000000..f050cc9fa
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/ContainerCommand.java
@@ -0,0 +1,19 @@
+package com.symphony.bdk.cli.command;
+
+import picocli.CommandLine.Model.CommandSpec;
+import picocli.CommandLine.Spec;
+
+/**
+ * Base class for noun (container) commands such as {@code message} or {@code stream}. When invoked
+ * without a verb subcommand, it prints its own usage and performs no Symphony call.
+ */
+public abstract class ContainerCommand implements Runnable {
+
+  @Spec
+  protected CommandSpec spec;
+
+  @Override
+  public void run() {
+    spec.commandLine().usage(spec.commandLine().getOut());
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/WhoamiCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/WhoamiCommand.java
new file mode 100644
index 000000000..4844807b8
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/WhoamiCommand.java
@@ -0,0 +1,17 @@
+package com.symphony.bdk.cli.command;
+
+import picocli.CommandLine.Command;
+
+/**
+ * {@code bdk whoami} — print the authenticated bot's session identity (a connectivity smoke test).
+ */
+@Command(
+    name = "whoami",
+    description = "Print the authenticated bot's session identity.")
+public class WhoamiCommand extends BaseCommand {
+
+  @Override
+  public Integer call() throws Exception {
+    return emit(bdk().sessions().getSession());
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/datafeed/DatafeedCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/datafeed/DatafeedCommand.java
new file mode 100644
index 000000000..913628c23
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/datafeed/DatafeedCommand.java
@@ -0,0 +1,15 @@
+package com.symphony.bdk.cli.command.datafeed;
+
+import com.symphony.bdk.cli.command.ContainerCommand;
+
+import picocli.CommandLine.Command;
+
+/** {@code bdk datafeed} — stream real-time events. */
+@Command(
+    name = "datafeed",
+    description = "Read the bot's real-time event feed.",
+    subcommands = {
+        DatafeedReadCommand.class
+    })
+public class DatafeedCommand extends ContainerCommand {
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/datafeed/DatafeedReadCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/datafeed/DatafeedReadCommand.java
new file mode 100644
index 000000000..67482a2bc
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/datafeed/DatafeedReadCommand.java
@@ -0,0 +1,87 @@
+package com.symphony.bdk.cli.command.datafeed;
+
+import com.symphony.bdk.cli.command.BaseCommand;
+import com.symphony.bdk.cli.internal.DurationConverter;
+import com.symphony.bdk.cli.internal.Json;
+import com.symphony.bdk.core.service.datafeed.DatafeedLoop;
+import com.symphony.bdk.core.service.datafeed.RealTimeEventListener;
+import com.symphony.bdk.gen.api.model.UserV2;
+import com.symphony.bdk.gen.api.model.V4Event;
+
+import picocli.CommandLine;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+import java.io.PrintWriter;
+import java.time.Duration;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+/**
+ * {@code bdk datafeed read} — print each real-time event as a single JSON object on its own line
+ * (NDJSON / JSON Lines). The loop stops after {@code --count} events, after {@code --timeout}, or on
+ * SIGINT, always shutting the datafeed loop down cleanly before the process exits.
+ */
+@Command(
+    name = "read",
+    description = "Stream real-time events as JSON Lines until a bound or interruption.")
+public class DatafeedReadCommand extends BaseCommand {
+
+  @Option(names = "--count", paramLabel = "<N>", description = "Stop after N events.")
+  Integer count;
+
+  @Option(
+      names = "--timeout",
+      paramLabel = "<duration>",
+      converter = DurationConverter.class,
+      description = "Stop after this duration (e.g. 30s, 5m, 1h).")
+  Duration timeout;
+
+  @Override
+  public Integer call() throws Exception {
+    final DatafeedLoop loop = bdk().datafeed();
+    final PrintWriter out = spec.commandLine().getOut();
+    final AtomicInteger emitted = new AtomicInteger();
+
+    loop.subscribe(new RealTimeEventListener() {
+      @Override
+      public boolean isAcceptingEvent(V4Event event, UserV2 botInfo) {
+        synchronized (out) {
+          out.println(Json.compact(event));
+          out.flush();
+        }
+        if (count != null && emitted.incrementAndGet() >= count) {
+          loop.stop();
+        }
+        return true;
+      }
+    });
+
+    // SIGINT (Ctrl-C) → stop the loop cleanly
+    final Thread shutdownHook = new Thread(loop::stop, "bdk-datafeed-shutdown");
+    Runtime.getRuntime().addShutdownHook(shutdownHook);
+
+    // optional time bound
+    ScheduledExecutorService scheduler = null;
+    if (timeout != null) {
+      scheduler = Executors.newSingleThreadScheduledExecutor();
+      scheduler.schedule(loop::stop, timeout.toMillis(), TimeUnit.MILLISECONDS);
+    }
+
+    try {
+      loop.start(); // blocks until stop() is called
+    } finally {
+      if (scheduler != null) {
+        scheduler.shutdownNow();
+      }
+      try {
+        Runtime.getRuntime().removeShutdownHook(shutdownHook);
+      } catch (IllegalStateException alreadyShuttingDown) {
+        // JVM is already shutting down (SIGINT path); nothing to remove
+      }
+    }
+    return CommandLine.ExitCode.OK;
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/health/HealthCheckCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/health/HealthCheckCommand.java
new file mode 100644
index 000000000..82ffcc71b
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/health/HealthCheckCommand.java
@@ -0,0 +1,17 @@
+package com.symphony.bdk.cli.command.health;
+
+import com.symphony.bdk.cli.command.BaseCommand;
+
+import picocli.CommandLine.Command;
+
+/** {@code bdk health check}. */
+@Command(
+    name = "check",
+    description = "Report the health status of the agent and connected components.")
+public class HealthCheckCommand extends BaseCommand {
+
+  @Override
+  public Integer call() throws Exception {
+    return emit(bdk().health().healthCheck());
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/health/HealthCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/health/HealthCommand.java
new file mode 100644
index 000000000..0de1a0bfe
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/health/HealthCommand.java
@@ -0,0 +1,15 @@
+package com.symphony.bdk.cli.command.health;
+
+import com.symphony.bdk.cli.command.ContainerCommand;
+
+import picocli.CommandLine.Command;
+
+/** {@code bdk health} — check connectivity to Symphony components. */
+@Command(
+    name = "health",
+    description = "Check the health of the bot's connected Symphony components.",
+    subcommands = {
+        HealthCheckCommand.class
+    })
+public class HealthCommand extends ContainerCommand {
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageCommand.java
new file mode 100644
index 000000000..a639acbe2
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageCommand.java
@@ -0,0 +1,17 @@
+package com.symphony.bdk.cli.command.message;
+
+import com.symphony.bdk.cli.command.ContainerCommand;
+
+import picocli.CommandLine.Command;
+
+/** {@code bdk message} — send and read messages. */
+@Command(
+    name = "message",
+    description = "Send and read messages.",
+    subcommands = {
+        MessageSendCommand.class,
+        MessageGetCommand.class,
+        MessageListCommand.class
+    })
+public class MessageCommand extends ContainerCommand {
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageGetCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageGetCommand.java
new file mode 100644
index 000000000..a120a009c
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageGetCommand.java
@@ -0,0 +1,27 @@
+package com.symphony.bdk.cli.command.message;
+
+import com.symphony.bdk.cli.command.BaseCommand;
+import com.symphony.bdk.cli.internal.NotFoundException;
+import com.symphony.bdk.gen.api.model.V4Message;
+
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Parameters;
+
+/** {@code bdk message get <messageId>}. */
+@Command(
+    name = "get",
+    description = "Retrieve a single message by id.")
+public class MessageGetCommand extends BaseCommand {
+
+  @Parameters(index = "0", paramLabel = "<messageId>", description = "Message id to retrieve.")
+  String messageId;
+
+  @Override
+  public Integer call() throws Exception {
+    final V4Message message = bdk().messages().getMessage(messageId);
+    if (message == null) {
+      throw NotFoundException.of("message", messageId);
+    }
+    return emit(message);
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageListCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageListCommand.java
new file mode 100644
index 000000000..cbb56a2a0
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageListCommand.java
@@ -0,0 +1,49 @@
+package com.symphony.bdk.cli.command.message;
+
+import com.symphony.bdk.cli.command.BaseCommand;
+import com.symphony.bdk.core.service.pagination.model.PaginationAttribute;
+
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+import picocli.CommandLine.Parameters;
+
+import java.time.Duration;
+import java.time.Instant;
+
+/** {@code bdk message list <streamId> [--since <ts>] [--limit N] [--skip N]}. */
+@Command(
+    name = "list",
+    description = "List messages in a stream.")
+public class MessageListCommand extends BaseCommand {
+
+  @Parameters(index = "0", paramLabel = "<streamId>", description = "Stream id to read from.")
+  String streamId;
+
+  @Option(
+      names = "--since",
+      paramLabel = "<ts>",
+      description = "Lower time bound: epoch millis or ISO-8601 instant. Default: last 24h.")
+  String since;
+
+  @Option(names = "--limit", defaultValue = "50", description = "Max messages to return (default: ${DEFAULT-VALUE}).")
+  int limit;
+
+  @Option(names = "--skip", defaultValue = "0", description = "Messages to skip (default: ${DEFAULT-VALUE}).")
+  int skip;
+
+  @Override
+  public Integer call() throws Exception {
+    final Instant sinceInstant = parseSince(since);
+    return emit(bdk().messages().listMessages(streamId, sinceInstant, new PaginationAttribute(skip, limit)));
+  }
+
+  private static Instant parseSince(String value) {
+    if (value == null || value.isBlank()) {
+      return Instant.now().minus(Duration.ofHours(24));
+    }
+    if (value.matches("\\d+")) {
+      return Instant.ofEpochMilli(Long.parseLong(value));
+    }
+    return Instant.parse(value);
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageSendCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageSendCommand.java
new file mode 100644
index 000000000..57667c3a1
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/message/MessageSendCommand.java
@@ -0,0 +1,29 @@
+package com.symphony.bdk.cli.command.message;
+
+import com.symphony.bdk.cli.command.BaseCommand;
+
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+import picocli.CommandLine.Parameters;
+
+/** {@code bdk message send <streamId> --message "<text>"}. */
+@Command(
+    name = "send",
+    description = "Send a message to a stream.")
+public class MessageSendCommand extends BaseCommand {
+
+  @Parameters(index = "0", paramLabel = "<streamId>", description = "Target stream id.")
+  String streamId;
+
+  @Option(
+      names = {"-m", "--message"},
+      required = true,
+      paramLabel = "<text>",
+      description = "Message body (MessageML or plain text).")
+  String message;
+
+  @Override
+  public Integer call() throws Exception {
+    return emit(bdk().messages().send(streamId, message));
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamCommand.java
new file mode 100644
index 000000000..21dd9c476
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamCommand.java
@@ -0,0 +1,17 @@
+package com.symphony.bdk.cli.command.stream;
+
+import com.symphony.bdk.cli.command.ContainerCommand;
+
+import picocli.CommandLine.Command;
+
+/** {@code bdk stream} — inspect the bot's streams. */
+@Command(
+    name = "stream",
+    description = "List streams, members and stream details.",
+    subcommands = {
+        StreamListCommand.class,
+        StreamMembersCommand.class,
+        StreamGetCommand.class
+    })
+public class StreamCommand extends ContainerCommand {
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamGetCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamGetCommand.java
new file mode 100644
index 000000000..0f0c99884
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamGetCommand.java
@@ -0,0 +1,27 @@
+package com.symphony.bdk.cli.command.stream;
+
+import com.symphony.bdk.cli.command.BaseCommand;
+import com.symphony.bdk.cli.internal.NotFoundException;
+import com.symphony.bdk.gen.api.model.V2StreamAttributes;
+
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Parameters;
+
+/** {@code bdk stream get <streamId>}. */
+@Command(
+    name = "get",
+    description = "Get a stream's details.")
+public class StreamGetCommand extends BaseCommand {
+
+  @Parameters(index = "0", paramLabel = "<streamId>", description = "Stream id.")
+  String streamId;
+
+  @Override
+  public Integer call() throws Exception {
+    final V2StreamAttributes stream = bdk().streams().getStream(streamId);
+    if (stream == null) {
+      throw NotFoundException.of("stream", streamId);
+    }
+    return emit(stream);
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamListCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamListCommand.java
new file mode 100644
index 000000000..32bb36318
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamListCommand.java
@@ -0,0 +1,25 @@
+package com.symphony.bdk.cli.command.stream;
+
+import com.symphony.bdk.cli.command.BaseCommand;
+import com.symphony.bdk.core.service.pagination.model.PaginationAttribute;
+
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+/** {@code bdk stream list [--limit N] [--skip N]}. */
+@Command(
+    name = "list",
+    description = "List the streams the bot is a member of.")
+public class StreamListCommand extends BaseCommand {
+
+  @Option(names = "--limit", defaultValue = "50", description = "Max streams to return (default: ${DEFAULT-VALUE}).")
+  int limit;
+
+  @Option(names = "--skip", defaultValue = "0", description = "Streams to skip (default: ${DEFAULT-VALUE}).")
+  int skip;
+
+  @Override
+  public Integer call() throws Exception {
+    return emit(bdk().streams().listStreams(null, new PaginationAttribute(skip, limit)));
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamMembersCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamMembersCommand.java
new file mode 100644
index 000000000..968b3d400
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/stream/StreamMembersCommand.java
@@ -0,0 +1,21 @@
+package com.symphony.bdk.cli.command.stream;
+
+import com.symphony.bdk.cli.command.BaseCommand;
+
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Parameters;
+
+/** {@code bdk stream members <streamId>}. */
+@Command(
+    name = "members",
+    description = "List the members of a stream.")
+public class StreamMembersCommand extends BaseCommand {
+
+  @Parameters(index = "0", paramLabel = "<streamId>", description = "Stream id.")
+  String streamId;
+
+  @Override
+  public Integer call() throws Exception {
+    return emit(bdk().streams().listStreamMembers(streamId));
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserCommand.java
new file mode 100644
index 000000000..029fc3c7c
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserCommand.java
@@ -0,0 +1,16 @@
+package com.symphony.bdk.cli.command.user;
+
+import com.symphony.bdk.cli.command.ContainerCommand;
+
+import picocli.CommandLine.Command;
+
+/** {@code bdk user} — look up and search users. */
+@Command(
+    name = "user",
+    description = "Look up and search users.",
+    subcommands = {
+        UserGetCommand.class,
+        UserSearchCommand.class
+    })
+public class UserCommand extends ContainerCommand {
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserGetCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserGetCommand.java
new file mode 100644
index 000000000..4015f617e
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserGetCommand.java
@@ -0,0 +1,51 @@
+package com.symphony.bdk.cli.command.user;
+
+import com.symphony.bdk.cli.command.BaseCommand;
+import com.symphony.bdk.cli.internal.NotFoundException;
+import com.symphony.bdk.core.service.user.UserService;
+import com.symphony.bdk.gen.api.model.UserV2;
+
+import picocli.CommandLine;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Parameters;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.regex.Pattern;
+
+/**
+ * {@code bdk user get <emailOrId>} — detects whether the argument is a numeric user id or an email
+ * address and looks the user up accordingly.
+ */
+@Command(
+    name = "get",
+    description = "Get a user by numeric id or email address.")
+public class UserGetCommand extends BaseCommand {
+
+  private static final Pattern NUMERIC = Pattern.compile("\\d+");
+  private static final Pattern EMAIL = Pattern.compile("^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$");
+
+  @Parameters(index = "0", paramLabel = "<emailOrId>", description = "Numeric user id or email address.")
+  String identifier;
+
+  @Override
+  public Integer call() throws Exception {
+    // detect the lookup mode before authenticating, so a malformed argument is a pure usage error
+    final boolean byId = NUMERIC.matcher(identifier).matches();
+    final boolean byEmail = !byId && EMAIL.matcher(identifier).matches();
+    if (!byId && !byEmail) {
+      throw new CommandLine.ParameterException(spec.commandLine(),
+          "'" + identifier + "' is neither a numeric user id nor an email address");
+    }
+
+    final UserService users = bdk().users();
+    final List<UserV2> matches = byId
+        ? users.listUsersByIds(Collections.singletonList(Long.parseLong(identifier)))
+        : users.listUsersByEmails(Collections.singletonList(identifier));
+
+    if (matches == null || matches.isEmpty()) {
+      throw NotFoundException.of("user", identifier);
+    }
+    return emit(matches.get(0));
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserSearchCommand.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserSearchCommand.java
new file mode 100644
index 000000000..2290d916b
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/command/user/UserSearchCommand.java
@@ -0,0 +1,34 @@
+package com.symphony.bdk.cli.command.user;
+
+import com.symphony.bdk.cli.command.BaseCommand;
+import com.symphony.bdk.core.service.pagination.model.PaginationAttribute;
+import com.symphony.bdk.gen.api.model.UserSearchQuery;
+
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+import picocli.CommandLine.Parameters;
+
+/** {@code bdk user search <query> [--local] [--limit N] [--skip N]}. */
+@Command(
+    name = "search",
+    description = "Search users by a free-text query.")
+public class UserSearchCommand extends BaseCommand {
+
+  @Parameters(index = "0", paramLabel = "<query>", description = "Free-text search query.")
+  String query;
+
+  @Option(names = "--local", description = "Restrict the search to the local pod.")
+  boolean local;
+
+  @Option(names = "--limit", defaultValue = "50", description = "Max users to return (default: ${DEFAULT-VALUE}).")
+  int limit;
+
+  @Option(names = "--skip", defaultValue = "0", description = "Users to skip (default: ${DEFAULT-VALUE}).")
+  int skip;
+
+  @Override
+  public Integer call() throws Exception {
+    final UserSearchQuery searchQuery = new UserSearchQuery().query(query);
+    return emit(bdk().users().searchUsers(searchQuery, local, new PaginationAttribute(skip, limit)));
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/BdkCliExecutionExceptionHandler.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/BdkCliExecutionExceptionHandler.java
new file mode 100644
index 000000000..28362bcc5
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/BdkCliExecutionExceptionHandler.java
@@ -0,0 +1,73 @@
+package com.symphony.bdk.cli.internal;
+
+import com.symphony.bdk.core.auth.exception.AuthInitializationException;
+import com.symphony.bdk.core.auth.exception.AuthUnauthorizedException;
+import com.symphony.bdk.http.api.ApiException;
+import com.symphony.bdk.http.api.ApiRuntimeException;
+
+import picocli.CommandLine;
+import picocli.CommandLine.IExecutionExceptionHandler;
+import picocli.CommandLine.ParseResult;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * Serialises any exception thrown while executing a command to a JSON envelope on {@code stderr}
+ * and maps it to a stable, documented exit code.
+ *
+ * <table>
+ *   <caption>Exit codes</caption>
+ *   <tr><td>0</td><td>success</td></tr>
+ *   <tr><td>1</td><td>generic / unexpected error</td></tr>
+ *   <tr><td>2</td><td>authentication failure</td></tr>
+ *   <tr><td>3</td><td>not found / API 404</td></tr>
+ *   <tr><td>64</td><td>usage error (handled by picocli's default parameter exception handler)</td></tr>
+ * </table>
+ */
+public class BdkCliExecutionExceptionHandler implements IExecutionExceptionHandler {
+
+  /** Authentication failed. */
+  public static final int EXIT_AUTH = 2;
+  /** Targeted resource does not exist. */
+  public static final int EXIT_NOT_FOUND = 3;
+  /**
+   * Usage error (bad arguments). Set to the conventional {@code EX_USAGE} value rather than
+   * picocli's {@code ExitCode.USAGE} ({@code 2}), which would collide with {@link #EXIT_AUTH}.
+   */
+  public static final int EXIT_USAGE = 64;
+
+  @Override
+  public int handleExecutionException(Exception ex, CommandLine cmd, ParseResult parseResult) {
+    final Map<String, Object> envelope = new LinkedHashMap<>();
+    envelope.put("error", ex.getMessage() != null ? ex.getMessage() : ex.toString());
+    envelope.put("type", ex.getClass().getSimpleName());
+
+    cmd.getErr().println(Json.pretty(envelope));
+    cmd.getErr().flush();
+
+    return exitCodeFor(ex);
+  }
+
+  /** Maps an exception (walking its cause chain) to the documented exit code. */
+  public static int exitCodeFor(Throwable ex) {
+    for (Throwable t = ex; t != null; t = t.getCause()) {
+      if (t instanceof AuthInitializationException || t instanceof AuthUnauthorizedException) {
+        return EXIT_AUTH;
+      }
+      if (t instanceof NotFoundException) {
+        return EXIT_NOT_FOUND;
+      }
+      if (t instanceof ApiRuntimeException && ((ApiRuntimeException) t).getCode() == 404) {
+        return EXIT_NOT_FOUND;
+      }
+      if (t instanceof ApiException && ((ApiException) t).getCode() == 404) {
+        return EXIT_NOT_FOUND;
+      }
+      if (t instanceof CommandLine.ParameterException) {
+        return EXIT_USAGE;
+      }
+    }
+    return CommandLine.ExitCode.SOFTWARE; // 1
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/DurationConverter.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/DurationConverter.java
new file mode 100644
index 000000000..81cc3cc40
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/DurationConverter.java
@@ -0,0 +1,50 @@
+package com.symphony.bdk.cli.internal;
+
+import picocli.CommandLine.ITypeConverter;
+import picocli.CommandLine.TypeConversionException;
+
+import java.time.Duration;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Parses a human-friendly duration such as {@code 30s}, {@code 5m}, {@code 1h} or {@code 500ms}.
+ * A bare number is interpreted as seconds. ISO-8601 durations ({@code PT30S}) are also accepted.
+ */
+public class DurationConverter implements ITypeConverter<Duration> {
+
+  private static final Pattern SHORTHAND = Pattern.compile("(?i)\\s*(\\d+)\\s*(ms|s|m|h)?\\s*");
+
+  @Override
+  public Duration convert(String value) {
+    if (value == null || value.isBlank()) {
+      throw new TypeConversionException("empty duration");
+    }
+    final String trimmed = value.trim();
+    if (trimmed.regionMatches(true, 0, "P", 0, 1)) {
+      try {
+        return Duration.parse(trimmed);
+      } catch (Exception e) {
+        throw new TypeConversionException("invalid ISO-8601 duration: '" + value + "'");
+      }
+    }
+    final Matcher m = SHORTHAND.matcher(trimmed);
+    if (!m.matches()) {
+      throw new TypeConversionException("invalid duration: '" + value + "' (use e.g. 30s, 5m, 1h)");
+    }
+    final long n = Long.parseLong(m.group(1));
+    final String unit = m.group(2) == null ? "s" : m.group(2).toLowerCase();
+    switch (unit) {
+      case "ms":
+        return Duration.ofMillis(n);
+      case "s":
+        return Duration.ofSeconds(n);
+      case "m":
+        return Duration.ofMinutes(n);
+      case "h":
+        return Duration.ofHours(n);
+      default:
+        throw new TypeConversionException("invalid duration unit: '" + unit + "'");
+    }
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/Json.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/Json.java
new file mode 100644
index 000000000..d45bbd457
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/Json.java
@@ -0,0 +1,50 @@
+package com.symphony.bdk.cli.internal;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+
+import java.io.UncheckedIOException;
+
+/**
+ * Shared Jackson serialisation for CLI output.
+ *
+ * <p>Command results are written to {@code stdout} as JSON. A pretty-printed form is used for
+ * single-document results ({@link #pretty(Object)}); a single-line form is used for the {@code
+ * datafeed read} JSON Lines stream ({@link #compact(Object)}).
+ */
+public final class Json {
+
+  private static final ObjectMapper MAPPER = new ObjectMapper()
+      .registerModule(new JavaTimeModule())
+      .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
+      .disable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
+      .setSerializationInclusion(JsonInclude.Include.NON_NULL);
+
+  private static final ObjectWriter PRETTY = MAPPER.writerWithDefaultPrettyPrinter();
+  private static final ObjectWriter COMPACT = MAPPER.writer();
+
+  private Json() {
+  }
+
+  /** Serialise {@code value} as an indented, multi-line JSON document. */
+  public static String pretty(Object value) {
+    return write(PRETTY, value);
+  }
+
+  /** Serialise {@code value} as a single-line JSON document (one NDJSON record). */
+  public static String compact(Object value) {
+    return write(COMPACT, value);
+  }
+
+  private static String write(ObjectWriter writer, Object value) {
+    try {
+      return writer.writeValueAsString(value);
+    } catch (JsonProcessingException e) {
+      throw new UncheckedIOException(e);
+    }
+  }
+}
diff --git a/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/NotFoundException.java b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/NotFoundException.java
new file mode 100644
index 000000000..19c55e0b4
--- /dev/null
+++ b/symphony-bdk-cli/src/main/java/com/symphony/bdk/cli/internal/NotFoundException.java
@@ -0,0 +1,17 @@
+package com.symphony.bdk.cli.internal;
+
+/**
+ * Raised when a command targets a resource (message, stream, user, …) that does not exist.
+ * Mapped to exit code {@code 3} by {@link BdkCliExecutionExceptionHandler}.
+ */
+public class NotFoundException extends RuntimeException {
+
+  public NotFoundException(String message) {
+    super(message);
+  }
+
+  /** Convenience factory: {@code no <kind> found for '<identifier>'}. */
+  public static NotFoundException of(String kind, Object identifier) {
+    return new NotFoundException("no " + kind + " found for '" + identifier + "'");
+  }
+}
diff --git a/symphony-bdk-cli/src/main/resources/logback.xml b/symphony-bdk-cli/src/main/resources/logback.xml
new file mode 100644
index 000000000..b0e94be2e
--- /dev/null
+++ b/symphony-bdk-cli/src/main/resources/logback.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  CLI logging configuration.
+
+  All logs are written to ~/.symphony/cli/cli.log so that stdout stays a clean,
+  parseable JSON channel for command results. The log file rolls daily and keeps
+  30 days of history capped at 50 MB total. The default level is WARN; the
+  verbose flag (-v) raises the root level to DEBUG programmatically at runtime
+  (see BdkCli).
+-->
+<configuration>
+
+  <property name="LOG_DIR" value="${user.home}/.symphony/cli"/>
+
+  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+    <file>${LOG_DIR}/cli.log</file>
+    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+      <fileNamePattern>${LOG_DIR}/cli.%d{yyyy-MM-dd}.log</fileNamePattern>
+      <maxHistory>30</maxHistory>
+      <totalSizeCap>50MB</totalSizeCap>
+    </rollingPolicy>
+    <encoder>
+      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+    </encoder>
+  </appender>
+
+  <root level="${LOG_LEVEL:-WARN}">
+    <appender-ref ref="FILE"/>
+  </root>
+
+</configuration>
diff --git a/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/BdkCliWiringTest.java b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/BdkCliWiringTest.java
new file mode 100644
index 000000000..d4904a80c
--- /dev/null
+++ b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/BdkCliWiringTest.java
@@ -0,0 +1,54 @@
+package com.symphony.bdk.cli;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.jupiter.api.Test;
+import picocli.CommandLine;
+
+import java.nio.file.Paths;
+import java.util.Map;
+
+/** Verifies the picocli command tree, option parsing and default config resolution. */
+class BdkCliWiringTest {
+
+  @Test
+  void registersAllNounCommands() {
+    final Map<String, CommandLine> subs = BdkCli.commandLine(new BdkCli()).getSubcommands();
+    assertThat(subs.keySet())
+        .contains("whoami", "message", "stream", "user", "datafeed", "health");
+  }
+
+  @Test
+  void registersVerbSubcommands() {
+    final Map<String, CommandLine> subs = BdkCli.commandLine(new BdkCli()).getSubcommands();
+    assertThat(subs.get("message").getSubcommands().keySet()).contains("send", "get", "list");
+    assertThat(subs.get("stream").getSubcommands().keySet()).contains("list", "members", "get");
+    assertThat(subs.get("user").getSubcommands().keySet()).contains("get", "search");
+    assertThat(subs.get("datafeed").getSubcommands().keySet()).contains("read");
+    assertThat(subs.get("health").getSubcommands().keySet()).contains("check");
+  }
+
+  @Test
+  void defaultConfigPathPointsAtSymphonyDir() {
+    final BdkCli app = new BdkCli();
+    BdkCli.commandLine(app).parseArgs("whoami");
+    assertThat(app.configPath.toString()).endsWith(".symphony/config.yaml");
+    assertThat(app.configPath.toString()).startsWith(System.getProperty("user.home"));
+  }
+
+  @Test
+  void parsesGlobalOptions() {
+    final BdkCli app = new BdkCli();
+    BdkCli.commandLine(app).parseArgs("-c", "/tmp/other.yaml", "-v", "whoami");
+    assertThat(app.configPath).isEqualTo(Paths.get("/tmp/other.yaml"));
+    assertThat(app.verbose).isTrue();
+  }
+
+  @Test
+  void longFormOptionsParse() {
+    final BdkCli app = new BdkCli();
+    BdkCli.commandLine(app).parseArgs("--config", "/tmp/x.yaml", "--verbose", "whoami");
+    assertThat(app.configPath).isEqualTo(Paths.get("/tmp/x.yaml"));
+    assertThat(app.verbose).isTrue();
+  }
+}
diff --git a/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/CliTestBase.java b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/CliTestBase.java
new file mode 100644
index 000000000..55ad34b7b
--- /dev/null
+++ b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/CliTestBase.java
@@ -0,0 +1,40 @@
+package com.symphony.bdk.cli;
+
+import com.symphony.bdk.core.SymphonyBdk;
+
+import picocli.CommandLine;
+
+import java.io.PrintWriter;
+import java.io.StringWriter;
+
+/** Shared harness: runs the CLI with captured stdout/stderr and a (usually mocked) BDK facade. */
+abstract class CliTestBase {
+
+  protected StringWriter out;
+  protected StringWriter err;
+
+  /** Run with a pre-built facade injected via the test seam. */
+  protected int execute(SymphonyBdk bdk, String... args) {
+    final BdkCli app = new BdkCli();
+    app.setBdk(bdk);
+    return run(app, args);
+  }
+
+  /** Run an arbitrary (possibly overridden) root command instance. */
+  protected int run(BdkCli app, String... args) {
+    out = new StringWriter();
+    err = new StringWriter();
+    final CommandLine cmd = BdkCli.commandLine(app);
+    cmd.setOut(new PrintWriter(out, true));
+    cmd.setErr(new PrintWriter(err, true));
+    return cmd.execute(args);
+  }
+
+  protected String stdout() {
+    return out.toString();
+  }
+
+  protected String stderr() {
+    return err.toString();
+  }
+}
diff --git a/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/CommandTest.java b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/CommandTest.java
new file mode 100644
index 000000000..7fbd83511
--- /dev/null
+++ b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/CommandTest.java
@@ -0,0 +1,181 @@
+package com.symphony.bdk.cli;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyList;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.symphony.bdk.core.SymphonyBdk;
+import com.symphony.bdk.core.service.pagination.model.PaginationAttribute;
+import com.symphony.bdk.core.service.health.HealthService;
+import com.symphony.bdk.core.service.message.MessageService;
+import com.symphony.bdk.core.service.session.SessionService;
+import com.symphony.bdk.core.service.stream.StreamService;
+import com.symphony.bdk.core.service.user.UserService;
+import com.symphony.bdk.gen.api.model.StreamAttributes;
+import com.symphony.bdk.gen.api.model.UserSearchQuery;
+import com.symphony.bdk.gen.api.model.UserV2;
+import com.symphony.bdk.gen.api.model.V2MembershipList;
+import com.symphony.bdk.gen.api.model.V2StreamAttributes;
+import com.symphony.bdk.gen.api.model.V3Health;
+import com.symphony.bdk.gen.api.model.V3HealthStatus;
+import com.symphony.bdk.gen.api.model.V4Message;
+
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.time.Instant;
+import java.util.Collections;
+import java.util.List;
+
+/** Per-command behaviour against a fully mocked {@link SymphonyBdk} facade. */
+class CommandTest extends CliTestBase {
+
+  private static final ObjectMapper JSON = new ObjectMapper();
+
+  @Test
+  void whoamiPrintsSession() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final SessionService sessions = mock(SessionService.class);
+    when(bdk.sessions()).thenReturn(sessions);
+    when(sessions.getSession()).thenReturn(new UserV2().id(7L).username("bot"));
+
+    assertThat(execute(bdk, "whoami")).isZero();
+    assertThat(JSON.readTree(stdout()).get("username").asText()).isEqualTo("bot");
+  }
+
+  @Test
+  void messageSendPostsAndPrintsResult() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final MessageService messages = mock(MessageService.class);
+    when(bdk.messages()).thenReturn(messages);
+    when(messages.send(eq("STREAM1"), eq("hello"))).thenReturn(new V4Message().messageId("MSG1"));
+
+    assertThat(execute(bdk, "message", "send", "STREAM1", "--message", "hello")).isZero();
+    verify(messages).send("STREAM1", "hello");
+    assertThat(JSON.readTree(stdout()).get("messageId").asText()).isEqualTo("MSG1");
+  }
+
+  @Test
+  void messageGetPrintsMessage() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final MessageService messages = mock(MessageService.class);
+    when(bdk.messages()).thenReturn(messages);
+    when(messages.getMessage("MSG1")).thenReturn(new V4Message().messageId("MSG1").message("hi"));
+
+    assertThat(execute(bdk, "message", "get", "MSG1")).isZero();
+    assertThat(JSON.readTree(stdout()).get("message").asText()).isEqualTo("hi");
+  }
+
+  @Test
+  void messageListPrintsJsonArray() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final MessageService messages = mock(MessageService.class);
+    when(bdk.messages()).thenReturn(messages);
+    when(messages.listMessages(eq("STREAM1"), any(Instant.class), any(PaginationAttribute.class)))
+        .thenReturn(List.of(new V4Message().messageId("A"), new V4Message().messageId("B")));
+
+    assertThat(execute(bdk, "message", "list", "STREAM1")).isZero();
+    final JsonNode array = JSON.readTree(stdout());
+    assertThat(array.isArray()).isTrue();
+    assertThat(array).hasSize(2);
+  }
+
+  @Test
+  void streamListPrintsJsonArray() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final StreamService streams = mock(StreamService.class);
+    when(bdk.streams()).thenReturn(streams);
+    when(streams.listStreams(any(), any())).thenReturn(List.of(new StreamAttributes().id("S1")));
+
+    assertThat(execute(bdk, "stream", "list")).isZero();
+    assertThat(JSON.readTree(stdout()).isArray()).isTrue();
+  }
+
+  @Test
+  void streamMembersPrintsResult() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final StreamService streams = mock(StreamService.class);
+    when(bdk.streams()).thenReturn(streams);
+    when(streams.listStreamMembers("S1")).thenReturn(new V2MembershipList());
+
+    assertThat(execute(bdk, "stream", "members", "S1")).isZero();
+    assertThat(JSON.readTree(stdout())).isNotNull();
+  }
+
+  @Test
+  void streamGetPrintsStream() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final StreamService streams = mock(StreamService.class);
+    when(bdk.streams()).thenReturn(streams);
+    when(streams.getStream("S1")).thenReturn(new V2StreamAttributes().id("S1"));
+
+    assertThat(execute(bdk, "stream", "get", "S1")).isZero();
+    assertThat(JSON.readTree(stdout()).get("id").asText()).isEqualTo("S1");
+  }
+
+  @Test
+  void userGetByNumericIdUsesIdLookup() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final UserService users = mock(UserService.class);
+    when(bdk.users()).thenReturn(users);
+    when(users.listUsersByIds(anyList())).thenReturn(List.of(new UserV2().id(42L)));
+
+    assertThat(execute(bdk, "user", "get", "42")).isZero();
+    final ArgumentCaptor<List<Long>> captor = ArgumentCaptor.forClass(List.class);
+    verify(users).listUsersByIds(captor.capture());
+    assertThat(captor.getValue()).containsExactly(42L);
+    assertThat(JSON.readTree(stdout()).get("id").asLong()).isEqualTo(42L);
+  }
+
+  @Test
+  void userGetByEmailUsesEmailLookup() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final UserService users = mock(UserService.class);
+    when(bdk.users()).thenReturn(users);
+    when(users.listUsersByEmails(anyList()))
+        .thenReturn(List.of(new UserV2().emailAddress("a@b.com")));
+
+    assertThat(execute(bdk, "user", "get", "a@b.com")).isZero();
+    verify(users).listUsersByEmails(Collections.singletonList("a@b.com"));
+    assertThat(JSON.readTree(stdout()).get("emailAddress").asText()).isEqualTo("a@b.com");
+  }
+
+  @Test
+  void userGetNotFoundExitsThree() {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final UserService users = mock(UserService.class);
+    when(bdk.users()).thenReturn(users);
+    when(users.listUsersByIds(anyList())).thenReturn(Collections.emptyList());
+
+    assertThat(execute(bdk, "user", "get", "999")).isEqualTo(3);
+  }
+
+  @Test
+  void userSearchPrintsJsonArray() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final UserService users = mock(UserService.class);
+    when(bdk.users()).thenReturn(users);
+    when(users.searchUsers(any(UserSearchQuery.class), any(), any()))
+        .thenReturn(List.of(new UserV2().id(1L), new UserV2().id(2L)));
+
+    assertThat(execute(bdk, "user", "search", "alice")).isZero();
+    assertThat(JSON.readTree(stdout()).isArray()).isTrue();
+  }
+
+  @Test
+  void healthCheckPrintsStatus() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final HealthService health = mock(HealthService.class);
+    when(bdk.health()).thenReturn(health);
+    when(health.healthCheck()).thenReturn(new V3Health().status(V3HealthStatus.UP));
+
+    assertThat(execute(bdk, "health", "check")).isZero();
+    assertThat(JSON.readTree(stdout()).get("status").asText()).isEqualTo("UP");
+  }
+}
diff --git a/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/DatafeedReadTest.java b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/DatafeedReadTest.java
new file mode 100644
index 000000000..eed25c10d
--- /dev/null
+++ b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/DatafeedReadTest.java
@@ -0,0 +1,49 @@
+package com.symphony.bdk.cli;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.atLeastOnce;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.symphony.bdk.core.SymphonyBdk;
+import com.symphony.bdk.core.service.datafeed.DatafeedLoop;
+import com.symphony.bdk.core.service.datafeed.RealTimeEventListener;
+import com.symphony.bdk.gen.api.model.V4Event;
+
+import org.junit.jupiter.api.Test;
+
+/** Verifies the {@code datafeed read} JSON Lines stream and its bounded lifecycle. */
+class DatafeedReadTest extends CliTestBase {
+
+  @Test
+  void emitsEventsAsJsonLinesAndStopsOnCount() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final DatafeedLoop loop = mock(DatafeedLoop.class);
+    when(bdk.datafeed()).thenReturn(loop);
+
+    final RealTimeEventListener[] subscribed = new RealTimeEventListener[1];
+    doAnswer(invocation -> {
+      subscribed[0] = invocation.getArgument(0);
+      return null;
+    }).when(loop).subscribe(any());
+
+    // when the loop "starts", deliver an event to the registered listener
+    doAnswer(invocation -> {
+      subscribed[0].isAcceptingEvent(new V4Event().id("E1").type("MESSAGESENT"), null);
+      return null;
+    }).when(loop).start();
+
+    final int code = execute(bdk, "datafeed", "read", "--count", "1");
+
+    assertThat(code).isZero();
+    final String firstLine = stdout().trim().split("\\R")[0];
+    assertThat(new ObjectMapper().readTree(firstLine).get("id").asText()).isEqualTo("E1");
+    // count bound reached -> loop stopped cleanly
+    verify(loop).start();
+    verify(loop, atLeastOnce()).stop();
+  }
+}
diff --git a/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/ExitCodeTest.java b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/ExitCodeTest.java
new file mode 100644
index 000000000..bae93263f
--- /dev/null
+++ b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/ExitCodeTest.java
@@ -0,0 +1,115 @@
+package com.symphony.bdk.cli;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.symphony.bdk.cli.internal.BdkCliExecutionExceptionHandler;
+import com.symphony.bdk.cli.internal.NotFoundException;
+import com.symphony.bdk.core.SymphonyBdk;
+import com.symphony.bdk.core.auth.exception.AuthInitializationException;
+import com.symphony.bdk.core.auth.exception.AuthUnauthorizedException;
+import com.symphony.bdk.core.config.exception.BdkConfigException;
+import com.symphony.bdk.core.service.message.MessageService;
+import com.symphony.bdk.http.api.ApiException;
+import com.symphony.bdk.http.api.ApiRuntimeException;
+
+import org.junit.jupiter.api.Test;
+
+/** Verifies the documented exit-code contract and the JSON error envelope on stderr. */
+class ExitCodeTest extends CliTestBase {
+
+  @Test
+  void exitCodeMappingUnit() {
+    assertThat(BdkCliExecutionExceptionHandler.exitCodeFor(new AuthUnauthorizedException("x"))).isEqualTo(2);
+    assertThat(BdkCliExecutionExceptionHandler.exitCodeFor(new AuthInitializationException("x"))).isEqualTo(2);
+    assertThat(BdkCliExecutionExceptionHandler.exitCodeFor(new NotFoundException("x"))).isEqualTo(3);
+    assertThat(BdkCliExecutionExceptionHandler.exitCodeFor(new ApiException(404, "x"))).isEqualTo(3);
+    assertThat(BdkCliExecutionExceptionHandler.exitCodeFor(new ApiRuntimeException(new ApiException(404, "x")))).isEqualTo(3);
+    assertThat(BdkCliExecutionExceptionHandler.exitCodeFor(new ApiRuntimeException(new ApiException(500, "x")))).isEqualTo(1);
+    assertThat(BdkCliExecutionExceptionHandler.exitCodeFor(new RuntimeException("x"))).isEqualTo(1);
+    // cause-chain unwrapping
+    assertThat(BdkCliExecutionExceptionHandler.exitCodeFor(new RuntimeException(new AuthUnauthorizedException("x")))).isEqualTo(2);
+  }
+
+  @Test
+  void authFailureExitsTwo() {
+    final BdkCli app = new BdkCli() {
+      @Override
+      public SymphonyBdk bdk() throws AuthUnauthorizedException {
+        throw new AuthUnauthorizedException("invalid bot credentials");
+      }
+    };
+    final int code = run(app, "whoami");
+    assertThat(code).isEqualTo(2);
+    assertThat(stderr()).contains("\"error\"").contains("\"type\"").contains("AuthUnauthorizedException");
+    assertThat(stdout()).isEmpty();
+  }
+
+  @Test
+  void configErrorExitsNonZero() {
+    final BdkCli app = new BdkCli() {
+      @Override
+      public SymphonyBdk bdk() throws BdkConfigException {
+        throw new BdkConfigException("config not found");
+      }
+    };
+    final int code = run(app, "whoami");
+    assertThat(code).isNotZero();
+    assertThat(stderr()).contains("config not found");
+  }
+
+  @Test
+  void notFoundFromNullResultExitsThree() {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final MessageService messages = mock(MessageService.class);
+    when(bdk.messages()).thenReturn(messages);
+    when(messages.getMessage("missing")).thenReturn(null);
+
+    final int code = execute(bdk, "message", "get", "missing");
+    assertThat(code).isEqualTo(3);
+    assertThat(stderr()).contains("\"error\"").contains("missing");
+  }
+
+  @Test
+  void notFoundFromApi404ExitsThree() {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final MessageService messages = mock(MessageService.class);
+    when(bdk.messages()).thenReturn(messages);
+    when(messages.getMessage("gone")).thenThrow(new ApiRuntimeException(new ApiException(404, "not found")));
+
+    final int code = execute(bdk, "message", "get", "gone");
+    assertThat(code).isEqualTo(3);
+  }
+
+  @Test
+  void genericErrorExitsOne() {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final MessageService messages = mock(MessageService.class);
+    when(bdk.messages()).thenReturn(messages);
+    when(messages.getMessage("boom")).thenThrow(new RuntimeException("kaboom"));
+
+    final int code = execute(bdk, "message", "get", "boom");
+    assertThat(code).isEqualTo(1);
+    assertThat(stderr()).contains("kaboom");
+  }
+
+  @Test
+  void missingRequiredOptionExitsUsage64() {
+    final int code = execute(mock(SymphonyBdk.class), "message", "send", "STREAM_ID");
+    assertThat(code).isEqualTo(64);
+  }
+
+  @Test
+  void unknownSubcommandExitsUsage64() {
+    final int code = execute(mock(SymphonyBdk.class), "definitely-not-a-command");
+    assertThat(code).isEqualTo(64);
+  }
+
+  @Test
+  void ambiguousUserIdentifierExitsUsage64() {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final int code = execute(bdk, "user", "get", "not-an-id-or-email");
+    assertThat(code).isEqualTo(64);
+  }
+}
diff --git a/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/JsonOutputTest.java b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/JsonOutputTest.java
new file mode 100644
index 000000000..5292fef0a
--- /dev/null
+++ b/symphony-bdk-cli/src/test/java/com/symphony/bdk/cli/JsonOutputTest.java
@@ -0,0 +1,65 @@
+package com.symphony.bdk.cli;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.symphony.bdk.core.SymphonyBdk;
+import com.symphony.bdk.core.service.session.SessionService;
+import com.symphony.bdk.gen.api.model.UserV2;
+
+import ch.qos.logback.classic.Logger;
+import ch.qos.logback.classic.LoggerContext;
+import ch.qos.logback.classic.joran.JoranConfigurator;
+import ch.qos.logback.classic.spi.ILoggingEvent;
+import ch.qos.logback.core.Appender;
+import ch.qos.logback.core.ConsoleAppender;
+import org.junit.jupiter.api.Test;
+
+import java.io.InputStream;
+import java.util.Iterator;
+
+/** Verifies that command results are valid JSON on stdout and that logging is routed to stderr. */
+class JsonOutputTest extends CliTestBase {
+
+  @Test
+  void stdoutIsValidJsonDocument() throws Exception {
+    final SymphonyBdk bdk = mock(SymphonyBdk.class);
+    final SessionService sessions = mock(SessionService.class);
+    when(bdk.sessions()).thenReturn(sessions);
+    when(sessions.getSession()).thenReturn(new UserV2().id(12345L).displayName("Test Bot"));
+
+    final int code = execute(bdk, "whoami");
+
+    assertThat(code).isZero();
+    final JsonNode node = new ObjectMapper().readTree(stdout());
+    assertThat(node.get("id").asLong()).isEqualTo(12345L);
+    assertThat(node.get("displayName").asText()).isEqualTo("Test Bot");
+    // nothing but the JSON document on stdout
+    assertThat(stdout().trim()).startsWith("{").endsWith("}");
+    assertThat(stderr()).isEmpty();
+  }
+
+  @Test
+  void bundledLogbackRoutesAllAppendersToStderr() throws Exception {
+    // load the bundled config in isolation so the assertion is about the artifact, not ambient state
+    final LoggerContext context = new LoggerContext();
+    final JoranConfigurator configurator = new JoranConfigurator();
+    configurator.setContext(context);
+    try (InputStream config = getClass().getResourceAsStream("/logback.xml")) {
+      assertThat(config).as("bundled logback.xml is on the classpath").isNotNull();
+      configurator.doConfigure(config);
+    }
+
+    final Logger root = context.getLogger(Logger.ROOT_LOGGER_NAME);
+    final Iterator<Appender<ILoggingEvent>> appenders = root.iteratorForAppenders();
+    assertThat(appenders.hasNext()).as("root logger has at least one appender").isTrue();
+    while (appenders.hasNext()) {
+      final Appender<ILoggingEvent> appender = appenders.next();
+      assertThat(appender).isInstanceOf(ConsoleAppender.class);
+      assertThat(((ConsoleAppender<ILoggingEvent>) appender).getTarget()).isEqualTo("System.err");
+    }
+  }
+}
diff --git a/symphony-bdk-config/src/main/java/com/symphony/bdk/core/config/BdkConfigParser.java b/symphony-bdk-config/src/main/java/com/symphony/bdk/core/config/BdkConfigParser.java
index 0e754c433..7e718b412 100644
--- a/symphony-bdk-config/src/main/java/com/symphony/bdk/core/config/BdkConfigParser.java
+++ b/symphony-bdk-config/src/main/java/com/symphony/bdk/core/config/BdkConfigParser.java
@@ -57,7 +57,7 @@ public JsonNode parseJsonNode(InputStream inputStream) throws BdkConfigException
     try {
       return JSON_MAPPER.readTree(content);
     } catch (IOException e) {
-      log.error("Error: {}", e.getMessage());
+      log.debug("Config file is not in JSON format.");
     }
 
     try {

From c4d5b2c4124f4ef0cec6d5f1d247785c91d28615 Mon Sep 17 00:00:00 2001
From: Thibault Pensec <thibault.pensec@symphony.com>
Date: Thu, 18 Jun 2026 12:58:39 +0200
Subject: [PATCH 2/3] chore: archive add-bdk-cli change and sync cli spec

Archive the completed add-bdk-cli openspec change and promote its delta
spec to the canonical location at openspec/specs/cli/spec.md.
---
 .../2026-06-18-add-bdk-cli}/.openspec.yaml    |   0
 .../2026-06-18-add-bdk-cli}/design.md         |   0
 .../2026-06-18-add-bdk-cli}/proposal.md       |   0
 .../2026-06-18-add-bdk-cli}/specs/cli/spec.md |   0
 .../2026-06-18-add-bdk-cli}/tasks.md          |   0
 openspec/specs/cli/spec.md                    | 151 ++++++++++++++++++
 6 files changed, 151 insertions(+)
 rename openspec/changes/{add-bdk-cli => archive/2026-06-18-add-bdk-cli}/.openspec.yaml (100%)
 rename openspec/changes/{add-bdk-cli => archive/2026-06-18-add-bdk-cli}/design.md (100%)
 rename openspec/changes/{add-bdk-cli => archive/2026-06-18-add-bdk-cli}/proposal.md (100%)
 rename openspec/changes/{add-bdk-cli => archive/2026-06-18-add-bdk-cli}/specs/cli/spec.md (100%)
 rename openspec/changes/{add-bdk-cli => archive/2026-06-18-add-bdk-cli}/tasks.md (100%)
 create mode 100644 openspec/specs/cli/spec.md

diff --git a/openspec/changes/add-bdk-cli/.openspec.yaml b/openspec/changes/archive/2026-06-18-add-bdk-cli/.openspec.yaml
similarity index 100%
rename from openspec/changes/add-bdk-cli/.openspec.yaml
rename to openspec/changes/archive/2026-06-18-add-bdk-cli/.openspec.yaml
diff --git a/openspec/changes/add-bdk-cli/design.md b/openspec/changes/archive/2026-06-18-add-bdk-cli/design.md
similarity index 100%
rename from openspec/changes/add-bdk-cli/design.md
rename to openspec/changes/archive/2026-06-18-add-bdk-cli/design.md
diff --git a/openspec/changes/add-bdk-cli/proposal.md b/openspec/changes/archive/2026-06-18-add-bdk-cli/proposal.md
similarity index 100%
rename from openspec/changes/add-bdk-cli/proposal.md
rename to openspec/changes/archive/2026-06-18-add-bdk-cli/proposal.md
diff --git a/openspec/changes/add-bdk-cli/specs/cli/spec.md b/openspec/changes/archive/2026-06-18-add-bdk-cli/specs/cli/spec.md
similarity index 100%
rename from openspec/changes/add-bdk-cli/specs/cli/spec.md
rename to openspec/changes/archive/2026-06-18-add-bdk-cli/specs/cli/spec.md
diff --git a/openspec/changes/add-bdk-cli/tasks.md b/openspec/changes/archive/2026-06-18-add-bdk-cli/tasks.md
similarity index 100%
rename from openspec/changes/add-bdk-cli/tasks.md
rename to openspec/changes/archive/2026-06-18-add-bdk-cli/tasks.md
diff --git a/openspec/specs/cli/spec.md b/openspec/specs/cli/spec.md
new file mode 100644
index 000000000..829225d95
--- /dev/null
+++ b/openspec/specs/cli/spec.md
@@ -0,0 +1,151 @@
+# CLI Specification
+
+### Requirement: CLI module and installable launcher
+The system SHALL provide a `symphony-bdk-cli` Gradle module that builds an installable `bdk`
+launcher via the Gradle `application` plugin's `installDist` task, with main class
+`com.symphony.bdk.cli.BdkCli`.
+
+#### Scenario: Building the distribution
+- **WHEN** a developer runs `./gradlew :symphony-bdk-cli:installDist`
+- **THEN** a runnable launcher is produced at `build/install/symphony-bdk-cli/bin/bdk` together
+  with all required runtime jars under `lib/`
+
+#### Scenario: Invoking on PATH
+- **WHEN** the `bdk` launcher is symlinked onto `PATH` and invoked as `bdk <noun> <verb> [args]`
+- **THEN** the corresponding command executes and the process exits with a documented exit code
+
+#### Scenario: No subcommand prints usage
+- **WHEN** `bdk` is invoked with no arguments
+- **THEN** the root usage/help is printed and the process exits without performing any Symphony call
+
+### Requirement: Configuration resolution
+The CLI SHALL load a `BdkConfig` from `~/.symphony/config.yaml` by default and SHALL accept a
+`-c`/`--config <path>` global option to override the location, using `BdkConfigLoader`.
+
+#### Scenario: Default configuration location
+- **WHEN** a command is run with no `--config` option and `~/.symphony/config.yaml` exists
+- **THEN** the CLI loads that file and authenticates the configured bot
+
+#### Scenario: Explicit configuration override
+- **WHEN** a command is run with `--config /path/to/other.yaml`
+- **THEN** the CLI loads the specified file instead of the default
+
+#### Scenario: Missing configuration
+- **WHEN** the resolved configuration file does not exist or cannot be parsed
+- **THEN** the CLI prints a JSON error to `stderr` and exits with a non-zero code without contacting Symphony
+
+### Requirement: Authentication as the configured bot
+The CLI SHALL authenticate as the bot described by the loaded configuration and SHALL perform all
+operations using that bot's session.
+
+#### Scenario: Successful authentication
+- **WHEN** a command is run with a configuration containing valid bot credentials
+- **THEN** the CLI authenticates the bot and performs the requested operation as that bot
+
+#### Scenario: Authentication failure
+- **WHEN** the bot credentials are invalid or authentication is rejected
+- **THEN** the CLI prints a JSON error to `stderr` and exits with code `2`
+
+### Requirement: JSON output on standard output
+In v1 the CLI SHALL emit command results as JSON on `stdout` and SHALL NOT provide any other
+output format.
+
+#### Scenario: Result serialised as JSON
+- **WHEN** a command completes successfully
+- **THEN** its result is written to `stdout` as a JSON document and nothing else is written to `stdout`
+
+#### Scenario: Logging does not pollute stdout
+- **WHEN** the BDK or its dependencies emit log output during a command
+- **THEN** that log output is written to `stderr`, leaving `stdout` as parseable JSON
+
+### Requirement: Error reporting and exit codes
+The CLI SHALL report errors as JSON on `stderr` and SHALL use stable, documented exit codes so
+that callers can branch on outcome without parsing text.
+
+#### Scenario: Error emitted as JSON
+- **WHEN** a command fails
+- **THEN** a JSON object containing at least an `error` message is written to `stderr`
+
+#### Scenario: Documented exit codes
+- **WHEN** a command fails due to authentication, the exit code is `2`; due to a not-found resource, `3`;
+  due to invalid arguments, `64`; for any other error, `1`
+- **THEN** the process terminates with the corresponding code, while success terminates with `0`
+
+### Requirement: `whoami` command
+The CLI SHALL provide a `bdk whoami` command that prints the authenticated bot's session identity.
+
+#### Scenario: Print bot identity
+- **WHEN** `bdk whoami` is run with a valid configuration
+- **THEN** the bot's session details (such as user id and display name from `sessions()`) are printed as JSON on `stdout`
+
+### Requirement: Message commands
+The CLI SHALL provide `bdk message send`, `bdk message get` and `bdk message list` commands backed
+by the BDK `MessageService`.
+
+#### Scenario: Send a message
+- **WHEN** `bdk message send <streamId> --message "<text>"` is run
+- **THEN** the message is sent to the stream and the resulting message id is printed as JSON
+
+#### Scenario: Get a message by id
+- **WHEN** `bdk message get <messageId>` is run
+- **THEN** the message is retrieved and printed as JSON, or exit code `3` is returned if it does not exist
+
+#### Scenario: List messages in a stream
+- **WHEN** `bdk message list <streamId>` is run, optionally with a `--since` timestamp
+- **THEN** the matching messages are printed as a JSON array
+
+### Requirement: Stream commands
+The CLI SHALL provide `bdk stream list`, `bdk stream members` and `bdk stream get` commands backed
+by the BDK `StreamService`.
+
+#### Scenario: List the bot's streams
+- **WHEN** `bdk stream list` is run
+- **THEN** the streams the bot is a member of are printed as a JSON array
+
+#### Scenario: List stream members
+- **WHEN** `bdk stream members <streamId>` is run
+- **THEN** the members of the stream are printed as a JSON array
+
+#### Scenario: Get stream details
+- **WHEN** `bdk stream get <streamId>` is run
+- **THEN** the stream's details are printed as JSON, or exit code `3` is returned if it does not exist
+
+### Requirement: User commands
+The CLI SHALL provide `bdk user get` and `bdk user search` commands backed by the BDK `UserService`.
+`bdk user get` SHALL accept a single positional argument and detect by pattern whether it is an
+email address or a numeric user id, looking the user up accordingly.
+
+#### Scenario: Get a user by id
+- **WHEN** `bdk user get <argument>` is run and the argument matches a numeric user id pattern
+- **THEN** the user is looked up by id and printed as JSON, or exit code `3` is returned if no such user exists
+
+#### Scenario: Get a user by email
+- **WHEN** `bdk user get <argument>` is run and the argument matches an email-address pattern
+- **THEN** the user is looked up by email and printed as JSON, or exit code `3` is returned if no such user exists
+
+#### Scenario: Search users
+- **WHEN** `bdk user search <query>` is run
+- **THEN** the matching users are printed as a JSON array
+
+### Requirement: Datafeed read command
+The CLI SHALL provide a `bdk datafeed read` command that streams real-time events as JSON Lines and
+terminates cleanly on a bound or interruption.
+
+#### Scenario: Stream events as JSON Lines
+- **WHEN** `bdk datafeed read` is run
+- **THEN** each received real-time event is printed as a single JSON object on its own line on `stdout`
+
+#### Scenario: Bounded read
+- **WHEN** `bdk datafeed read --count <N>` or `--timeout <duration>` is run
+- **THEN** the command stops the datafeed loop and exits with code `0` after the bound is reached
+
+#### Scenario: Interrupted read
+- **WHEN** the process receives SIGINT while reading
+- **THEN** the datafeed loop is stopped cleanly before the process exits
+
+### Requirement: Health check command
+The CLI SHALL provide a `bdk health check` command backed by the BDK `HealthService`.
+
+#### Scenario: Report health
+- **WHEN** `bdk health check` is run
+- **THEN** the health status of the bot's connected Symphony components is printed as JSON

From e3b12b9b84a176c04caf1b22c9bcf792d869740c Mon Sep 17 00:00:00 2001
From: Thibault Pensec <thibault.pensec@symphony.com>
Date: Thu, 18 Jun 2026 13:12:00 +0200
Subject: [PATCH 3/3] fix: route CLI logs to stderr and add release CLI upload
 step

Replace RollingFileAppender with ConsoleAppender(System.err) in logback.xml
so logs never pollute the JSON stdout channel. Add CLI binary upload step to
the release workflow so bdk/bdk.bat are attached to GitHub Releases.
---
 .github/workflows/release.yml                 | 11 ++++++++++
 .../src/main/resources/logback.xml            | 21 ++++++-------------
 2 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 8e393874e..21b2fc426 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -29,3 +29,14 @@ jobs:
           MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
           GPG_KEY_ID: ${{ secrets.GPG_KEY_ID }}
           GPG_KEY_PASSPHRASE: ${{ secrets.GPG_KEY_PASSPHRASE }}
+
+      - name: Build CLI distribution
+        run: ./gradlew :symphony-bdk-cli:installDist
+
+      - name: Upload CLI binaries to GitHub Release
+        run: |
+          gh release upload "${{ github.event.release.tag_name }}" \
+            symphony-bdk-cli/build/install/symphony-bdk-cli/bin/bdk \
+            symphony-bdk-cli/build/install/symphony-bdk-cli/bin/bdk.bat
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/symphony-bdk-cli/src/main/resources/logback.xml b/symphony-bdk-cli/src/main/resources/logback.xml
index b0e94be2e..05d09fe54 100644
--- a/symphony-bdk-cli/src/main/resources/logback.xml
+++ b/symphony-bdk-cli/src/main/resources/logback.xml
@@ -2,30 +2,21 @@
 <!--
   CLI logging configuration.
 
-  All logs are written to ~/.symphony/cli/cli.log so that stdout stays a clean,
-  parseable JSON channel for command results. The log file rolls daily and keeps
-  30 days of history capped at 50 MB total. The default level is WARN; the
-  verbose flag (-v) raises the root level to DEBUG programmatically at runtime
-  (see BdkCli).
+  All logs are written to stderr so that stdout stays a clean, parseable JSON
+  channel for command results. The default level is WARN; the verbose flag (-v)
+  raises the root level to DEBUG programmatically at runtime (see BdkCli).
 -->
 <configuration>
 
-  <property name="LOG_DIR" value="${user.home}/.symphony/cli"/>
-
-  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
-    <file>${LOG_DIR}/cli.log</file>
-    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
-      <fileNamePattern>${LOG_DIR}/cli.%d{yyyy-MM-dd}.log</fileNamePattern>
-      <maxHistory>30</maxHistory>
-      <totalSizeCap>50MB</totalSizeCap>
-    </rollingPolicy>
+  <appender name="STDERR" class="ch.qos.logback.core.ConsoleAppender">
+    <target>System.err</target>
     <encoder>
       <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
     </encoder>
   </appender>
 
   <root level="${LOG_LEVEL:-WARN}">
-    <appender-ref ref="FILE"/>
+    <appender-ref ref="STDERR"/>
   </root>
 
 </configuration>