Skip to content

CLAUDE.md

Latest commit

 

History

History
60 lines (45 loc) · 3.16 KB

CLAUDE.md

File metadata and controls

60 lines (45 loc) · 3.16 KB
Raw

OCL CLI

Command-line interface for the Open Concept Lab (OCL) API.

Setup

cd /Users/jonathanpayne/projects/ocl/ocl-cli
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Architecture

  • src/ocl_cli/api_client.py — Sync HTTP client with all high-level API methods. Business logic lives here (not in Click commands) so it can be reused by a future MCP server wrapper.
  • src/ocl_cli/config.py — Server registry and auth token resolution. Config stored at ~/.ocl/config.json.
  • src/ocl_cli/output.py — JSON and human-readable table formatters.
  • src/ocl_cli/main.py — Click root group, global options, command registration.
  • src/ocl_cli/commands/ — Thin Click command wrappers that parse args → call client → format output.

Conventions

  • Click commands are thin wrappers. All API logic goes in api_client.py.
  • Default owner_type is "orgs" for targeted operations, "all" for search/list.
  • Default repo_type is "all" for search/list, required for targeted operations.
  • --json / -j global flag outputs raw API JSON (unmodified) for agent consumption.
  • --debug / -d global flag shows HTTP requests on stderr.
  • --show-request global flag shows server URL and API request paths on stderr (cleaner than --debug).
  • --verbose per-command flag on search/list commands passes ?verbose=true to the OCL API, which returns full details (names, descriptions, extras) instead of summary. Default is summary (no verbose).
  • Version parameters are type-specific: --repo-version for sources/repos, --collection-version for collections, --concept-version for concept versions. Never use a bare --version for these.
  • Exit codes: 0=success, 1=client error (4xx), 2=server error (5xx), 3=auth error.
  • When changing command arguments or flags, always update README.md and docs/demos/ to match.

Running

ocl --help
ocl whoami --token YOUR_TOKEN
ocl concept search malaria --owner CIEL --source CIEL

Testing

pytest

Related repos

  • ocl-mcp — MCP server for AI assistants (async, different interface)
  • ocl-docs — API documentation at docs.openconceptlab.org
  • oclapi2 — The OCL API backend

Issues / Tickets

  • Issues for ocl-cli are tracked in the cross-repo tracker OpenConceptLab/ocl_issues on GitHub (not in this repo, and not on Gitea). Use gh CLI.
  • Contribution conventions are org-wide. All OCL repos inherit OpenConceptLab/.github/CONTRIBUTING.md — ticket-first, PR template, type/ labels, no direct pushes to main. In short: every PR links an issue — use closes OpenConceptLab/ocl_issues#N on the resolving commit (bare #N for partial work). Heads-up for agents: the org PR template only auto-fills in the GitHub web UI, so when opening PRs via gh, add the Closes #N line to the PR body yourself.
  • Code lives at OpenConceptLab/ocl-cli on GitHub. Changes go via feature branch + PR — never commit directly to main.
  • A pre-2026-05 archive of issues exists at gitea.lab.jpayne.me/ocl/ocl-cli (read-only / closed); do not file new tickets there.