claudia-docs-cli/SPEC.md

Claudia Docs CLI — Project Specification

1. Concept & Vision

Claudia Docs CLI es una herramienta de línea de comandos que permite a Claudia (y otros agentes) interactuar con Claudia Docs sin necesidad de un navegador. Diseñado para ser invocado desde prompts, scripts y pipelines de automatización.

Propósito: Ser la interfaz preferida para agentes que necesitan crear documentos, guardar reasoning, y consultar información programáticamente.

Differential: No es un CLI genérico de API. Está optimizado para el flujo de trabajo de un agente de investigación.

---

2. Tech Stack

Componente	Tecnología	Pourquoi
Language	Go 1.21+	Startup rápido, single binary, cross-compile
CLI Framework	Cobra	Battle-tested (kubectl, Hugo), experiencia del equipo
HTTP Client	net/http (stdlib)	Sin dependencias extra
JWT	golang-jwt/jwt/v5	Maduro, mantenimiento activo
JSON	encoding/json (stdlib)	Rápido, sin dependencias
Config	spf13/viper	Manejo de config de forma idiomática

---

3. Installation

Binary Download (Recomendado para agentes)

# Linux/macOS
curl -fsSL https://releases.claudia-docs.io/latest/install.sh | bash

# Directo
curl -fsSL https://releases.claudia-docs.io/claudia-docs-linux-amd64 -o /usr/local/bin/claudia-docs
chmod +x /usr/local/bin/claudia-docs

Build from Source

git clone https://git.example.com/claudia-docs-cli.git
cd claudia-docs-cli
go build -o claudia-docs ./cmd/claudia-docs
./claudia-docs --version

npm (desarrolladores)

npm install -g @claudia/docs-cli

---

4. Command Structure

claudia-docs [global options] <command> [arguments]

GLOBAL OPTIONS:
  --server URL       API server URL (default: http://localhost:8000)
  --token JWT        JWT token (alternativa: CLAUDIA_TOKEN env var)
  --output format    Output format: json, text (default: json)
  --quiet            Suppress stdout, solo JSON
  --config path      Path to config file (default: ~/.claudia-docs.yaml)
  --verbose          Verbose output (debug)
  --version          Show version
  --help             Show help

---

4.1 Auth Commands

claudia-docs auth login

Autentica y guarda el token.

claudia-docs auth login -u <username> -p <password>

# Output JSON:
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_at": "2026-03-31T02:00:00Z"
  },
  "meta": { "command": "auth login", "duration_ms": 120 }
}

Flags:

• -u, --username (required): Username
• -p, --password (required): Password
• --save: Guardar token en config (~/.claudia-docs.yaml)

claudia-docs auth logout

Limpia el token guardado.

claudia-docs auth logout

claudia-docs auth status

Muestra estado de autenticación actual.

claudia-docs auth status

---

4.2 Document Commands

claudia-docs doc create

Crea un nuevo documento.

claudia-docs doc create [flags]

# Flags:
  -t, --title string       Título del documento (required)
  -c, --content string     Contenido markdown (default: "")
  -p, --project-id string  ID del proyecto (required)
  -f, --folder-id string   ID de carpeta (optional)
  -m, --metadata JSON      Metadata extra como JSON (optional)

# Ejemplo:
claudia-docs doc create \
  --title "Research: AI Trends 2026" \
  --content "# Research\n\nContenido..." \
  --project-id "uuid-proyecto"

Output:

{
  "success": true,
  "data": {
    "id": "uuid-doc",
    "title": "Research: AI Trends 2026",
    "project_id": "uuid-proyecto",
    "created_at": "2026-03-30T14:00:00Z"
  }
}

---

claudia-docs doc list

Lista documentos.

claudia-docs doc list [flags]

# Flags:
  -p, --project-id string  Filtrar por proyecto
  -f, --folder-id string    Filtrar por carpeta
  --limit int               Límite de resultados (default: 20)
  --offset int              Offset para paginación (default: 0)

# Ejemplo:
claudia-docs doc list --project-id "uuid-proyecto" --limit 10

---

claudia-docs doc get

Obtiene un documento por ID.

claudia-docs doc get <document-id> [flags]

# Flags:
  --include-reasoning       Incluir metadata de reasoning
  --include-tags            Incluir tags

# Ejemplo:
claudia-docs doc get uuid-doc --include-reasoning --output json

---

claudia-docs doc update

Actualiza un documento.

claudia-docs doc update <document-id> [flags]

# Flags:
  -t, --title string     Nuevo título
  -c, --content string   Nuevo contenido
  -f, --folder-id string Mover a carpeta

# Ejemplo:
claudia-docs doc update uuid-doc --title "Title v2"

---

claudia-docs doc delete

Elimina un documento.

claudia-docs doc delete <document-id> [--force]

# --force: Skip confirmación

---

4.3 Project Commands

claudia-docs project list

Lista proyectos del agente.

claudia-docs project list

claudia-docs project create

Crea un proyecto.

claudia-docs project create -n <name> [-d <description>]

claudia-docs project get

Obtiene un proyecto.

claudia-docs project get <project-id>

---

4.4 Folder Commands

claudia-docs folder list

Lista carpetas de un proyecto.

claudia-docs folder list --project-id <project-id> [--parent-id <folder-id>]

claudia-docs folder create

Crea una carpeta.

claudia-docs folder create --project-id <project-id> -n <name> [--parent-id <folder-id>]

---

4.5 Tag Commands

claudia-docs tag list

Lista todos los tags.

claudia-docs tag create

Crea un tag.

claudia-docs tag create -n <name> [--color <hex-color>]

claudia-docs tag add

Añade tag a documento.

claudia-docs tag add --doc-id <doc-id> --tag-id <tag-id>

---

4.6 Search Commands

claudia-docs search

Búsqueda full-text.

claudia-docs search [flags]

# Flags:
  -q, --query string     Texto a buscar (required)
  -p, --project-id string Filtrar por proyecto
  --tags string          Filtrar por tags (comma-separated)

# Ejemplo:
claudia-docs search --query "API design" --project-id uuid-proyecto

---

4.7 Reasoning Commands

claudia-docs reasoning save

Guarda reasoning de un agente.

claudia-docs reasoning save [flags]

# Flags:
  -d, --doc-id string          Documento asociado (required)
  -t, --type string             Tipo: research, planning, analysis, synthesis (required)
  -s, --steps JSON              Array de steps de reasoning (required)
  --confidence float             Confidence 0.0-1.0 (optional)
  --model string                Modelo fuente (optional)

# Ejemplo:
claudia-docs reasoning save \
  --doc-id uuid-doc \
  --type research \
  --steps '[{"step_id":"1","thought":"...","conclusion":"..."}]' \
  --confidence 0.85 \
  --model "claude-sonnet-4"

---

5. Output Format

JSON (default)

{
  "success": true|false,
  "data": { ... },
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  },
  "meta": {
    "command": "doc create",
    "duration_ms": 45,
    "server": "http://localhost:8000"
  }
}

Text (--output text)

✅ Document created: uuid-doc
   Title: Research: AI Trends 2026
   Created: 2026-03-30 14:00:00

Quiet Mode (--quiet)

Solo JSON, sin mensajes de status.

---

6. Configuration

File: ~/.claudia-docs.yaml

server: http://localhost:8000
token: ""  # Se llena tras auth login --save
output: json
timeout: 30s

# Agentes múltiples (para Operator)
agents:
  claudia:
    token: eyJhbGciOiJIUzI1NiIs...
    default_project: uuid-claudia
  other:
    token: eyJhbGciOiJIUzI1NiIs...
    default_project: uuid-other

Environment Variables

Variable	Override	Description
CLAUDIA_SERVER	--server	API server URL
CLAUDIA_TOKEN	--token	JWT token
CLAUDIA_OUTPUT	--output	Output format
CLAUDIA_AGENT	-	Agent profile en config

---

7. Agent Integration

Ejemplo: Claudia invocando CLI

#!/bin/bash
# Claudia save_reasoning.sh

SERVER="${CLAUDIA_SERVER:-http://localhost:8000}"
TOKEN="${CLAUDIA_TOKEN}"

# Login si no hay token
if [ -z "$TOKEN" ]; then
  TOKEN=$(claudia-docs auth login \
    -u "${AGENT_USER}" \
    -p "${AGENT_PASS}" \
    --save \
    --output json | jq -r '.data.token')
fi

# Guardar documento con reasoning
claudia-docs doc create \
  --title "Analysis: $TASK_ID" \
  --content "$(cat reasoning.md)" \
  --project-id "${PROJECT_ID}" \
  --output json | jq -r '.data.id' > /tmp/doc_id.txt

# Guardar reasoning steps
claudia-docs reasoning save \
  --doc-id "$(cat /tmp/doc_id.txt)" \
  --type research \
  --steps "$(cat steps.json)" \
  --confidence 0.85 \
  --model "claude-sonnet-4"

En contexto de agente (prompts)

[System] Para guardar reasoning, usa:
  claudia-docs reasoning save --doc-id <id> --type <type> --steps '<json>'

[Tool] claudia-docs doc create --title "..." --content "..."

---

8. Project Structure

claudia-docs-cli/
├── cmd/
│   └── claudia-docs/
│       └── main.go           # Entry point
├── internal/
│   ├── auth/
│   │   └── auth.go          # Login, JWT handling
│   ├── api/
│   │   ├── client.go         # HTTP client
│   │   ├── documents.go      # Document API calls
│   │   ├── projects.go       # Project API calls
│   │   ├── folders.go        # Folder API calls
│   │   ├── tags.go           # Tags API calls
│   │   ├── search.go         # Search API calls
│   │   └── reasoning.go      # Reasoning API calls
│   ├── config/
│   │   └── config.go         # Viper config
│   └── output/
│       └── output.go         # JSON/Text output formatting
├── pkg/
│   └── types/
│       └── types.go          # Shared types (para compartir con backend)
├── cobra/
│   └── commands.go           # Cobra command definitions
├── Makefile
├── go.mod
├── go.sum
└── README.md

---

9. Cross-Compilation

# Linux
GOOS=linux GOARCH=amd64 go build -o claudia-docs-linux-amd64 ./cmd/claudia-docs

# macOS
GOOS=darwin GOARCH=amd64 go build -o claudia-docs-darwin-amd64 ./cmd/claudia-docs
GOOS=darwin GOARCH=arm64 go build -o claudia-docs-darwin-arm64 ./cmd/claudia-docs

# Windows
GOOS=windows GOARCH=amd64 go build -o claudia-docs-windows-amd64.exe ./cmd/claudia-docs

---

10. Dependencies

// go.mod
module github.com/claudia/docs-cli

go 1.21

require (
    github.com/spf13/cobra v1.8.0
    github.com/spf13/viper v1.18.2
    github.com/golang-jwt/jwt/v5 v5.2.0
)

Sin dependencias externas para HTTP client ni JSON (stdlib).

---

11. Error Codes

Code	HTTP	Description
UNAUTHORIZED	401	Token inválido o expirado
FORBIDDEN	403	Sin permisos para el recurso
NOT_FOUND	404	Recurso no encontrado
VALIDATION_ERROR	422	Datos inválidos
SERVER_ERROR	500	Error interno del servidor
NETWORK_ERROR	-	No se pudo conectar al servidor

---

12. Roadmap

Phase 1: Core CLI (MVP)

• Auth: login, logout, status
• Documents: create, list, get, update, delete
• Projects: list, get
• Folders: list, get
• Output JSON/Text

Phase 2: Full Coverage

• Tags: CRUD + add/remove from docs
• Search
• Reasoning save/list/get

Phase 3: Advanced

• Batch operations (crear múltiples docs)
• File upload (--file path)
• Export documents
• Interactive mode (TUI)
• Shell completion

Phase 4: Agent Features

• Streaming output
• Webhook subscriptions
• Agent-to-agent communication

---

13. Open Questions

1. ¿Go o Rust? ¿Preferencia del equipo para Go vs Rust?
2. Distribución: ¿Binary-only es aceptable o se requiere npm/pip?
3. TUI interactivo: ¿Necesario en Phase 1 o Phase 3?
4. Agent profiles: ¿Soporte multi-agente desde inicio?

---

14. Metadata

Campo	Valor
Project	Claudia Docs CLI
Version	1.0.0
Status	Specification
Created	2026-03-30
Author	Claudia (Chief Researcher)
Language	Go 1.21+
Framework	Cobra