dog-cli 2025.12.7.post1

Documentation Oriented Grammar (DOG) CLI Tool

DOG

Documentation Oriented Grammar — A Markdown-native format for system documentation that serves humans and AI agents alike.

Available on: pypi

---

Quick Start

Installation

pip install dog-cli
# or with uv
uv add dog-cli

Basic Usage

# Validate your docs
dog lint docs/

# Format files
dog format docs/

# Generate project index
dog index docs/ --name "My Project"

# Search for concepts
dog search "login" --path docs/

# Get a specific document
dog get "@User" --path docs/

# List all documents
dog list --path docs/

# Serve documentation in browser
dog serve docs/

Example

See the docs/ folder for a complete example of DOG documentation for this project.

---

What is DOG?

.dog.md is a Markdown-native specification format. Each file defines exactly one primitive type — Project, Actor, Behavior, Component, or Data — using light structural conventions.

DOG serves as:

• Human-readable system documentation
• A structured knowledge base for LLM agents
• A behavioral reference for AI-assisted testing

Primitive Types

Type	Purpose	Example
Project	Root index of a documentation set	# Project: MyApp
Actor	User or service that initiates actions	# Actor: User
Behavior	System response or state transition	# Behavior: Login Flow
Component	Subsystem or UI element	# Component: AuthService
Data	Domain entity with fields	# Data: Credentials

Cross-References

Use sigils inside backticks to reference other concepts:

Syntax	Meaning
`@User`	Actor reference
`!Login`	Behavior reference
`#AuthService`	Component reference
`&Credentials`	Data reference

---

CLI Commands

dog lint <path>

Validate .dog.md files for structure and reference errors.

dog lint docs/
dog lint my-behavior.dog.md

dog format <path>

Format .dog.md files (normalize whitespace).

dog format docs/
dog format --check docs/  # Check without modifying

dog index <path> --name <name>

Generate or update a Project index file (index.dog.md).

dog index docs/ --name "My Project"

dog search <query>

Search documents using fuzzy matching. Returns top-k results sorted by relevance.

dog search "login"
dog search "#auth"              # Filter by Component type
dog search "user" --limit 5 --output json

Option	Description
--path, -p	Directory to search (default: .)
--limit, -l	Max results (default: 10)
--output, -o	text or json

Use sigil prefixes to filter by type: @ (Actor), ! (Behavior), # (Component), & (Data).

dog get <name>

Get a document by name with resolved references.

dog get "Login Flow"
dog get "@User"                 # Get Actor named User
dog get "#AuthService" --output json

Option	Description
--path, -p	Directory to search (default: .)
--output, -o	text or json

Use sigil prefixes to filter by type: @ (Actor), ! (Behavior), # (Component), & (Data).

dog list

List all documents.

dog list
dog list !                      # List only Behaviors
dog list --output json

Option	Description
--path, -p	Directory to search (default: .)
--output, -o	text or json

Use sigil prefixes to filter by type: @ (Actor), ! (Behavior), # (Component), & (Data).

dog patch <name>

Update specific sections of a DOG document programmatically.

dog patch "@User" --data '{"sections": {"Description": "Updated description"}}'
dog patch "Login" --data '{"sections": {"Outcome": "New outcome"}}'

Option	Description
--path, -p	Directory to search (default: .)
--data, -d	JSON patch data

dog serve <path>

Serve DOG documentation as HTML in the browser with hot-reload.

dog serve docs/
dog serve --host 0.0.0.0 --port 3000
dog serve docs/ --no-reload

Option	Description
--host, -h	Host to bind (default: 127.0.0.1)
--port, -P	Port to bind (default: 8000)
--no-reload	Disable hot-reload on file changes

Features:

• Color-coded reference links (red=Actor, blue=Behavior, purple=Component, green=Data)
• Renders index.dog.md as homepage when present
• Automatic favicon discovery (favicon.png or dog.png)
• Hot-reload on file changes

---

File Format Reference

Project

# Project: <Name>

## Description
<freeform text>

## Actors
- <actor name>

## Behaviors
- <behavior name>

## Components
- <component name>

## Data
- <data name>

## Notes
- <annotation>

Actor

# Actor: <Name>

## Description
<free text>

## Notes
- <annotation>

Behavior

# Behavior: <Name>

## Condition
- <prerequisite>

## Description
<free text with `@actor`, `!behavior`, `#component`, `&data` references>

## Outcome
- <expected effect>

## Notes
- <annotation>

Component

# Component: <Name>

## Description
<free text>

## State
- <state field>

## Events
- <event name>

## Notes
- <annotation>

Data

# Data: <Name>

## Description
<free text>

## Fields
- field_name: <description>

## Notes
- <annotation>

---

Why DOG?

Approach	Trade-offs
RAG/Vector Search	Requires embeddings, chunking strategy, retrieval tuning. Context can be fragmented or miss cross-references.
Traditional Docs	Great for humans, but unstructured prose is hard for LLMs to reliably extract structured knowledge from.
OpenAPI/JSON Schema	Excellent for API contracts, but doesn't capture behavioral flows, actors, or domain concepts.
DOG	Markdown-native, no infra needed. Structured enough for LLM parsing, readable enough for humans. Single source of truth.

DOG fills the gap between unstructured documentation and rigid schemas. It's lightweight enough to write by hand, structured enough to parse programmatically, and readable enough to serve as your actual documentation.

---

License

MIT