CLI for Documentation Robotics
npm install @documentation-robotics/cliTypeScript-based CLI for managing federated architecture data models across 12 interconnected layers.
This is the Documentation Robotics CLI - a production-ready command-line tool for creating, managing, and exporting comprehensive architecture models that span business requirements through technical implementation.
- ✅ Project structure initialized
- ✅ TypeScript configuration (strict mode)
- ✅ Core domain models (Element, Layer, Model, Manifest)
- ✅ Reference and Relationship registries for tracking dependencies
- ✅ File I/O utilities with atomic writes
- ✅ JSON schemas bundled (all 12 layers)
- ✅ Comprehensive unit tests
- ✅ Code formatted and configured for linting
```
cli/
├── src/
│ ├── cli.ts # Entry point
│ ├── core/ # Domain models
│ │ ├── element.ts # Individual architecture items
│ │ ├── layer.ts # Layer containers
│ │ ├── model.ts # Complete model orchestration
│ │ ├── manifest.ts # Model metadata (JSON)
│ │ ├── reference-registry.ts # Cross-layer reference tracking
│ │ └── relationship-registry.ts # Intra-layer relationship management
│ ├── types/
│ │ └── index.ts # TypeScript type definitions
│ ├── utils/
│ │ └── file-io.ts # File operations (atomic writes)
│ └── schemas/
│ └── bundled/ # All JSON schemas from spec/
│ ├── 01-motivation-layer.schema.json
│ ├── 02-business-layer.schema.json
│ ├── ... (all 12 layer schemas)
│ ├── relationship-catalog.json
│ ├── link-registry.json
│ └── common/
│ ├── relationships.schema.json
│ ├── predicates.schema.json
│ └── ...
├── tests/
│ └── unit/
│ ├── core/
│ │ ├── element.test.ts
│ │ ├── layer.test.ts
│ │ ├── manifest.test.ts
│ │ ├── model.test.ts
│ │ ├── reference-registry.test.ts
│ │ ├── relationship-registry.test.ts
│ │ └── element.integration.test.js
│ └── utils/
│ └── file-io.test.ts
├── dist/ # Compiled JavaScript
├── package.json
├── tsconfig.json
├── biome.json
└── README.md
- Node.js 18+ (npm included)
- Bun 1.3+ (optional, recommended for best performance)
- A Documentation Robotics model directory (.dr/)
`bashInstall the CLI globally
npm install -g @documentation-robotics/cli
$3
For contributing to the CLI:
`bash
Clone the repository
git clone https://github.com/tinkermonkey/documentation_robotics.git
cd documentation_robotics/cliInstall dependencies
npm installBuild TypeScript
npm run buildRun tests with Bun (preferred)
bun testOr run tests with Node.js
npm testFormat code
npm run formatRun CLI locally during development
node dist/cli.js --help
`$3
#### Option 1: Global Installation (Recommended)
`bash
Using npm
npm install -g @documentation-robotics/cliUsing bun
bun add -g @documentation-robotics/cliVerify installation
dr --version
`#### Option 2: Project-Local Installation
`bash
Install as a dev dependency
npm install --save-dev @documentation-robotics/cliOr add to package.json and run npm install
{
"devDependencies": {
"@documentation-robotics/cli": "^0.1.0"
}
}Run via npx
npx dr --help
`#### Option 3: Build from Source
`bash
Clone and build
git clone https://github.com/tinkermonkey/documentation_robotics.git
cd documentation_robotics/cli
npm install
npm run buildInstall globally from built dist
npm install -g .Or run directly
node dist/cli.js --help
`$3
#### Claude Code CLI Setup (for Chat Features)
Chat functionality requires Claude Code CLI to be installed and authenticated with your Anthropic account.
Install Claude Code:
1. Visit https://claude.ai/download
2. Follow installation instructions for your platform
3. Authenticate with your Anthropic account when prompted
Verify installation:
`bash
Check Claude Code CLI is available
which claudeRun without a model directory to test
claude --version
`#### Visualization Server
`bash
Run visualization server with custom port
dr visualize --port 3000Run without auto-opening browser
dr visualize --no-browser
`#### Telemetry & Observability (Optional)
The CLI supports comprehensive OpenTelemetry instrumentation for tracing, logging, and observability during development and testing. Telemetry is completely optional and incurs zero overhead in production builds due to compile-time constant elimination.
##### Features
- Command Tracing: All CLI commands create root spans with command name, arguments, and working directory
- Validator Instrumentation: Schema, naming, reference, and semantic validation stages produce nested spans
- Console Logging: Console output (
console.log, console.error, etc.) is automatically captured and correlated with traces
- Test Instrumentation: Tests can emit spans with test file names, test case names, pass/fail status, and error details
- Project Context: All telemetry includes your project name from the manifest for easy filtering
- Circuit-Breaker Protection: Graceful degradation if the telemetry collector is unavailable—no user-facing errors or blocking
- Compile-Time Configuration: Telemetry code is completely eliminated from production builds via dead-code elimination##### Setup
###### Prerequisites
- Node.js 18+
- An OpenTelemetry collector (optional, for viewing traces/logs)
###### Start an OTEL Collector (Optional)
Option 1: Use Your Own Collector
The CLI works with any OTLP-compatible collector (Jaeger, Zipkin, Grafana Tempo, Honeycomb, etc.).
Option 2: Use the Example SigNoz Stack
An example SigNoz configuration is provided in
docs/otel_example/:`bash
From the repository root
./docs/otel_example/signoz-stack.sh startWait for services to initialize (~30 seconds)
Access SigNoz UI at http://localhost:3301
OTEL Collector is available at http://localhost:4318
`docs/otel_example/README.md for details.###### Build and Run CLI with Telemetry
`bash
Build CLI with telemetry enabled
npm run build:debugSet telemetry endpoint (optional - defaults to localhost:4318)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318Run CLI commands - traces and logs will be sent to SigNoz
node dist/cli.js validate
node dist/cli.js list motivation
node dist/cli.js add business service my-service --name "My Service"View traces and logs in SigNoz UI
http://localhost:3301
`###### Verify Tracing
In SigNoz UI (http://localhost:3301):
1. View Command Traces:
- Navigate to "Traces" section
- Look for spans named
cli.execute
- Expand to see nested validator spans (validation.stage.schema, validation.stage.naming, etc.)
- Each span shows command name, arguments, working directory, and project name2. View Correlated Logs:
- Click on a command span to view details
- Switch to "Logs" tab to see console output captured during command execution
- Logs include severity level (INFO, WARN, ERROR) and trace context (traceId, spanId)
3. Filter by Project:
- Use the filter
dr.project.name = "YourProjectName" to isolate telemetry for a specific project
- Useful when multiple projects share the same collector###### Test Instrumentation
Tests can emit telemetry to verify logging behavior. Use the test instrumentation utilities:
`typescript
import { describe, test, beforeAll, afterAll } from 'bun:test';
import {
startTestFileSpan,
endTestFileSpan,
instrumentTest,
} from '../../src/telemetry/test-instrumentation.js';beforeAll(() => {
startTestFileSpan('tests/unit/my-feature.test.ts');
});
afterAll(() => {
endTestFileSpan();
});
describe('MyFeature', () => {
test(
'should validate input',
instrumentTest(
'should validate input',
async () => {
// Test logic here
expect(result).toBe(expected);
},
'MyFeature' // Suite name for organization
)
);
});
`Run tests with telemetry:
`bash
npm run build:debug
npm run testView test spans in SigNoz UI with attributes:
- test.file: Path to test file
- test.name: Test case name
- test.suite: Describe block name
- test.status: 'pass', 'fail', or 'skip'
- test.error.message and test.error.stack (for failed tests)
`###### Stop the Example Stack (if using)
`bash
./docs/otel_example/signoz-stack.sh stopTo remove all data and start fresh:
./docs/otel_example/signoz-stack.sh clean
`##### Configuration
| Variable | Default | Purpose |
|----------|---------|---------|
|
OTEL_EXPORTER_OTLP_ENDPOINT | http://localhost:4318 | OTLP collector endpoint (applies to both traces and logs) |
| OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | Derived from OTLP_ENDPOINT | Override for logs endpoint specifically |
| DR_TELEMETRY | Determined by build | Build-time flag (set via npm run build:debug) |##### Architecture
The telemetry system consists of:
1. Resilient OTLP Exporter - Exports traces with circuit-breaker pattern (30s backoff on failure)
2. Resilient Log Exporter - Exports logs with same circuit-breaker protection
3. Console Interceptor - Captures console output without modifying application code
4. Test Instrumentation - Provides utilities for creating test spans with standard attributes
5. Resource Attributes - Every trace and log includes:
-
service.name: dr-cli
- service.version: CLI version from package.json
- dr.project.name: Project name from manifest (if available, else unknown)##### Troubleshooting
###### Traces not appearing in SigNoz
1. Verify SigNoz is running:
`bash
curl http://localhost:13133 # OTEL Collector health check
curl http://localhost:3301 # SigNoz UI
`2. Check telemetry build:
`bash
# Verify build was done with DR_TELEMETRY=true
npm run build:debug
`3. Verify endpoint connectivity:
`bash
node dist/cli.js validate
# If SigNoz is unavailable, circuit-breaker activates silently after 500ms timeout
`4. Check resource attributes:
- In SigNoz, search for traces with filter
service.name = "dr-cli"
- Verify dr.project.name appears in span attributes###### "Circuit-breaker activated" messages
These are internal debug messages and do not affect CLI execution. They appear when:
- The OTLP collector is unreachable
- Export timeout (500ms) is exceeded
The CLI continues normally—no errors are shown to users.
##### Production Deployment
- Development builds (
npm run build:debug): Includes full telemetry code (~50KB overhead)
- Production builds (npm run build): Zero telemetry overhead via dead-code elimination
- Telemetry code is completely removed from production bundles at compile time##### Notes
- Telemetry is entirely optional and disabled in production builds
- The CLI gracefully handles missing SigNoz (no blocking, no user-visible errors)
- Traces and logs are sent asynchronously without blocking CLI commands
- Default OTLP collection endpoint:
http://localhost:4318 (standard OpenTelemetry receiver)
- Supported log severity levels: DEBUG, INFO, WARN, ERROR
- Automatic trace-log correlation via traceId and spanId$3
| Feature | Requirement | Notes |
| ------------- | ----------------- | ---------------------------------- |
| Basic CLI | Node.js 18+ | All commands work |
| Visualization | Node.js 18+ | WebSocket support required |
| Chat | Claude Code CLI | OAuth authentication via Claude Code |
| Telemetry | Docker Compose | Optional, for local SigNoz/OTLP tracing |
| Performance | Bun 1.3+ | Optional but recommended |
$3
#### Command Not Found
`bash
If "dr" is not found after global installation
npm install -g @documentation-robotics/cliCheck npm global location
npm config get prefixAdd to PATH if needed (macOS/Linux)
export PATH="$(npm config get prefix)/bin:$PATH"Add to PATH permanently (.bashrc or .zshrc)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
`#### Module Not Found Errors
`bash
Clear and reinstall
rm -rf node_modules package-lock.json
npm installRebuild
npm run build
`#### Test Failures
`bash
Check that all dependencies are installed
npm listReinstall with clean cache
npm cache clean --force
npm installRun tests with verbose output
DEBUG=* npm test
`Command Reference
All commands include detailed help. View help for any command:
`bash
dr --help # Show all commands
dr --help # Show command-specific help
dr element add --help # Show element add help
`$3
| Category | Command | Purpose |
| ----------------- | --------------------- | ---------------------------------------------------- |
| Model |
init | Initialize a new architecture model |
| | info | Show model information and statistics |
| | validate | Validate the complete model |
| Elements | add | Add an element to a layer |
| | update | Update an element |
| | delete | Delete an element |
| | show | Display element details |
| | list | List elements in a layer |
| | search | Search for elements by name/ID |
| Relationships | relationship add | Add intra-layer relationship |
| | relationship delete | Delete a relationship |
| | relationship list | List relationships for an element |
| Dependencies | trace | Trace element dependencies |
| | project | Project dependencies to a target layer |
| Export | export | Export to various formats (ArchiMate, OpenAPI, etc.) |
| Visualization | visualize | Launch interactive visualization server |
| AI | chat | Interactive Claude AI chat about model |
| Advanced | migrate | Migrate model to new spec version |
| | upgrade | Check for version upgrades |
| | conformance | Check spec conformance |
| | changeset | Manage model change tracking |$3
#### Create a New Model
`bash
Initialize model
dr init --name "My Architecture" --author "Team A"Add some elements
dr add motivation goal customer-satisfaction --name "Ensure customer satisfaction"
dr add business service-category order-mgmt --name "Order Management"
dr add api endpoint create-order --properties '{"method":"POST","path":"/orders"}'View the model
dr info
dr list api
`#### Search and Update Elements
`bash
Search for elements
dr search customerShow details
dr show api-endpoint-create-orderUpdate an element
dr update api-endpoint-create-order --name "Create Order API (v2)"Delete an element
dr delete api-endpoint-old-endpoint --force
`#### Analyze Dependencies
`bash
Trace dependencies for an element
dr trace api-endpoint-create-orderShow dependencies in a specific direction
dr trace api-endpoint-create-order --direction upShow element metrics
dr trace api-endpoint-create-order --metricsProject to another layer
dr project api-endpoint-create-order business
`#### Manage Relationships
`bash
Add a relationship
dr relationship add business-process-1 business-process-2 --predicate depends-onList relationships
dr relationship list business-process-1Show only outgoing relationships
dr relationship list business-process-1 --direction outgoingDelete a relationship
dr relationship delete business-process-1 business-process-2 --force
`#### Export and Visualize
`bash
Export to multiple formats
dr export archimate --output model.xml
dr export openapi --layers api --output api-spec.yaml
dr export markdown --output docs/architecture.mdLaunch visualization server
dr visualize
dr visualize --port 3000 --no-browser
`#### Chat
Interactive conversation with Claude about your architecture model.
Requirements: Claude Code CLI must be installed and authenticated. The chat functionality uses your Claude Code OAuth token, not an API key.
Install Claude Code:
1. Visit https://claude.ai/download
2. Follow installation instructions for your platform
3. Authenticate with your Anthropic account
CLI Usage:
`bash
dr chat
`The chat command:
- Launches an interactive conversation loop
- Uses Claude Code CLI with restricted tools (Bash, Read)
- Provides context about your model (manifest, layer statistics)
- Streams responses in real-time
- Exit with "exit", "quit", or "q"
Example:
`bash
$ dr chat
┌ Documentation Robotics Chat
└ Powered by Claude Code - Ask about your architecture modelYou: What are the dependencies for the create-order endpoint?
Claude: Let me check the model for you...
[Using tool: Bash]
[Tool result: Found dependencies...]
You: Show me the critical path in the business layer
Claude: I'll analyze the business layer relationships...
You: exit
└ Goodbye!
`WebSocket Chat (via
dr visualize):The visualization server provides WebSocket-based chat using JSON-RPC 2.0:
Request (send message):
`json
{
"jsonrpc": "2.0",
"method": "chat.send",
"params": {
"message": "What layers are in this model?"
},
"id": 1
}
`Notifications (streaming response):
Text content chunk:
`json
{
"jsonrpc": "2.0",
"method": "chat.response.chunk",
"params": {
"conversation_id": "conv-1-12345",
"content": "This model has 12 layers...",
"is_final": false,
"timestamp": "2025-01-02T12:00:00.000Z"
}
}
`Tool invocation notification:
`json
{
"jsonrpc": "2.0",
"method": "chat.tool.invoke",
"params": {
"conversation_id": "conv-1-12345",
"tool_name": "Bash",
"tool_input": { "command": "dr list api" },
"timestamp": "2025-01-02T12:00:00.000Z"
}
}
`Tool result notification:
`json
{
"jsonrpc": "2.0",
"method": "chat.tool.result",
"params": {
"conversation_id": "conv-1-12345",
"result": "output from tool execution",
"timestamp": "2025-01-02T12:00:00.000Z"
}
}
`Completion response:
`json
{
"jsonrpc": "2.0",
"result": {
"conversation_id": "conv-1-12345",
"status": "complete",
"exit_code": 0,
"full_response": "Complete response text...",
"timestamp": "2025-01-02T12:00:00.000Z"
},
"id": 1
}
`Error response:
`json
{
"jsonrpc": "2.0",
"error": {
"code": -32001,
"message": "Claude Code CLI not available"
},
"id": 1
}
`Error Codes:
-
-32001: Claude Code CLI not available (install Claude Code)
- -32002: Invalid parameters
- -32603: Internal error (process failure, timeout)#### Manage Changesets
`bash
Create a changeset
dr changeset create "v1.1 migration" --description "Migrate to new API structure"List changesets
dr changeset listApply a changeset
dr changeset apply "v1.1 migration"Revert a changeset
dr changeset revert "v1.1 migration"
`Core Classes
$3
Individual architecture items in the model. Supports:
- Properties with type-safe getters/setters
- Array properties with add/get operations
- References to other elements (cross-layer)
- Relationships with other elements (intra-layer)
`typescript
const element = new Element({
id: "motivation-goal-test",
type: "Goal",
name: "Test Goal",
description: "A test goal",
properties: { priority: "high" },
});element.setProperty("owner", "team-a");
element.addToArrayProperty("tags", "important");
`$3
Container for elements within a single layer. Supports:
- Add/get/delete/list operations
- Dirty tracking (unsaved changes)
- JSON serialization/deserialization
`typescript
const layer = new Layer("motivation");
layer.addElement(element);if (layer.isDirty()) {
await model.saveLayer("motivation");
layer.markClean();
}
`$3
Model metadata (JSON-based). Supports:
- Automatic timestamp management
- JSON serialization/deserialization
- Version tracking
`typescript
const manifest = new Manifest({
name: "Test Model",
version: "1.0.0",
description: "A test model",
specVersion: "0.6.0",
});const json = JSON.stringify(manifest.toJSON());
const deserialized = Manifest.fromJSON(json);
`$3
Central orchestrator for the complete architecture model. Supports:
- Lazy layer loading
- Manifest management
- Atomic persistence to
.dr/ directory structure`typescript
// Initialize a new model
const model = await Model.init(".", {
name: "My Model",
version: "1.0.0",
});// Load an existing model
const loaded = await Model.load(".");
// Save changes
await model.saveManifest();
await model.saveDirtyLayers();
`$3
Tracks cross-layer references between architecture elements. Provides:
- Add/query references by source, target, or type
- Reference validation and integrity checking
- Impact analysis (find all references to/from an element)
- Statistics on reference usage
`typescript
const refRegistry = new ReferenceRegistry();refRegistry.addReference({
source: "01-motivation-goal-create-customer",
target: "02-business-process-create-order",
type: "realizes",
});
const refsFrom = refRegistry.getReferencesFrom("01-motivation-goal-create-customer");
const refsTo = refRegistry.getReferencesTo("02-business-process-create-order");
`$3
Manages intra-layer relationships and their semantic metadata. Provides:
- Register relationship types with predicates and metadata
- Query relationships by source, layer, or predicate
- Validate relationship predicates
- Layer-specific relationship rules
`typescript
const relRegistry = new RelationshipRegistry();relRegistry.registerType({
id: "depends-on",
predicate: "depends-on",
category: "dependency",
});
relRegistry.addRelationship({
source: "02-process-create-order",
target: "02-process-validate-order",
predicate: "depends-on",
});
`File I/O Utilities
Atomic file operations for safe persistence:
`typescript
import { ensureDir, writeFile, readFile, writeJSON, readJSON, atomicWrite } from "@/utils/file-io";// Ensure directory exists
await ensureDir(".dr/layers");
// Atomic write (safe for crash recovery)
await atomicWrite(".dr/manifest.json", content);
// JSON operations
await writeJSON(".dr/layers/motivation.json", data, true);
const loaded = await readJSON(".dr/layers/motivation.json");
`Type Definitions
Core types defined in
src/types/index.ts:-
Element - Architecture item representation
- LayerData - Layer serialization format
- ManifestData - Manifest metadata
- Reference - Cross-layer references
- Relationship - Intra-layer relationships
- ModelOptions - Model configurationTesting
Comprehensive test coverage for core classes:
`bash
Run Bun tests (requires Bun runtime)
bun testRun specific test file
bun test tests/unit/core/element.test.tsWith coverage
bun test --coverageNode.js integration test
node tests/unit/core/element.integration.test.js
`Bundled Schemas
All JSON schemas from
spec/schemas/ are bundled:- Layer Schemas: 01-motivation through 12-testing
- Catalogs: relationship-catalog.json, link-registry.json
- Common Schemas: predicates, relationships, source-references, layer-extensions
These schemas are loaded at build time and do not require filesystem access at runtime.
Code Quality
- TypeScript: Strict mode with comprehensive type coverage
- Linting: Biome configured for code quality checks
- Formatting: Code formatted to project standards
Related Resources
- Specification:
/workspace/spec/`MIT