Obsidian CLI Learnings and Plan

Date: February 19, 2026

This document captures what we learned from Obsidian's CLI docs and local CLI checks, then maps those learnings into a concrete plan for AgenticFlow CLI docs and product hardening.

External Reference Studied

• Obsidian CLI docs: https://help.obsidian.md/cli

Local Trial Results (This Environment)

Commands tested:

• command -v obsidian

• obsidian --help

• obsidian help

• open -g -u 'obsidian://open'

Observed:

• obsidian binary is not in PATH in this environment.

• obsidian --help and obsidian help fail with command-not-found.

• URI launch command succeeds on macOS (open ...), which confirms launcher-level behavior can differ from binary CLI availability.

Implication:

• CLI docs must include environment checks and OS-specific troubleshooting early, not as an afterthought.

What Obsidian Does Well (Reusable Patterns)

• Starts with clear prerequisites and caveats.

• Uses task-first structure: install, quick start, examples, command reference, troubleshooting.

• Uses compact, copy-paste shell examples instead of long prose.

• Separates everyday user actions from developer-oriented actions.

• Documents instability/early-access caveats explicitly.

How We Should Mirror This for AgenticFlow CLI Docs

1. Lead with scope and boundaries:

   • public API key flow,

   • what is stable today,

   • what is currently limited.

2. Keep command examples executable and short.

3. Provide a single command model section (operation_id, path-param, query, body, --dry-run, --json).

4. Publish troubleshooting by environment:

   • missing CLI in PATH,

   • missing API key,

   • stale operation IDs vs OpenAPI snapshot.

Delivery Plan

Phase 1: Contract Cleanup

• Generate high-level command mappings from current OpenAPI snapshot (avoid hardcoded stale IDs).

• Add a CI check that fails if mapped operation IDs are not present in openapi.json.

Phase 2: Reliability and Coverage

• Keep call, ops, catalog as canonical surfaces.

• Add automated smoke tests for top public runtime flows (health, node-types, anonymous workflow run/status, anonymous agent stream metadata paths).

Phase 3: Documentation Quality

• Maintain one CLI hub and one capabilities page with strict public-only examples.

• Add an explicit "Known Limitations (dated)" section to prevent stale assumptions.

• Keep docs examples synchronized to tested commands.

Phase 4: Release Gate

Before each CLI release:

1. ops list --public-only returns expected count/signature.

2. high-level wrappers pass mapping validation.

3. docs commands are re-smoke-tested and still valid.

4. release note includes any public contract changes.

Immediate Actions Completed

• Added CLI docs hub and capability page under docs/09-developers/cli/.

• Linked docs for developer navigation.

• Documented current limitation window with an explicit date.