Initial MVP implementation of Claudia Docs CLI
- Auth commands: login, logout, status - Document commands: create, list, get, update, delete - Project commands: list, get - Folder commands: list, create - Tag commands: list, create, add - Search command - Reasoning save command - JSON output format with --output text option - Viper-based configuration management - Cobra CLI framework
This commit is contained in:
Claudia CLI Bot
564
SPEC.md
Normal file
564
SPEC.md
Normal file
@@ -0,0 +1,564 @@
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
claudia-docs auth logout
|
||||
```
|
||||
|
||||
#### `claudia-docs auth status`
|
||||
Muestra estado de autenticación actual.
|
||||
|
||||
```bash
|
||||
claudia-docs auth status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Document Commands
|
||||
|
||||
#### `claudia-docs doc create`
|
||||
Crea un nuevo documento.
|
||||
|
||||
```bash
|
||||
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:**
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
claudia-docs doc delete <document-id> [--force]
|
||||
|
||||
# --force: Skip confirmación
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Project Commands
|
||||
|
||||
#### `claudia-docs project list`
|
||||
Lista proyectos del agente.
|
||||
|
||||
```bash
|
||||
claudia-docs project list
|
||||
```
|
||||
|
||||
#### `claudia-docs project create`
|
||||
Crea un proyecto.
|
||||
|
||||
```bash
|
||||
claudia-docs project create -n <name> [-d <description>]
|
||||
```
|
||||
|
||||
#### `claudia-docs project get`
|
||||
Obtiene un proyecto.
|
||||
|
||||
```bash
|
||||
claudia-docs project get <project-id>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.4 Folder Commands
|
||||
|
||||
#### `claudia-docs folder list`
|
||||
Lista carpetas de un proyecto.
|
||||
|
||||
```bash
|
||||
claudia-docs folder list --project-id <project-id> [--parent-id <folder-id>]
|
||||
```
|
||||
|
||||
#### `claudia-docs folder create`
|
||||
Crea una carpeta.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
claudia-docs tag create -n <name> [--color <hex-color>]
|
||||
```
|
||||
|
||||
#### `claudia-docs tag add`
|
||||
Añade tag a documento.
|
||||
|
||||
```bash
|
||||
claudia-docs tag add --doc-id <doc-id> --tag-id <tag-id>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.6 Search Commands
|
||||
|
||||
#### `claudia-docs search`
|
||||
Búsqueda full-text.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
```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
|
||||
|
||||
```bash
|
||||
#!/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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
// 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)
|
||||
- [x] Auth: login, logout, status
|
||||
- [x] Documents: create, list, get, update, delete
|
||||
- [x] Projects: list, get
|
||||
- [x] Folders: list, get
|
||||
- [x] Output JSON/Text
|
||||
|
||||
### Phase 2: Full Coverage
|
||||
- [x] Tags: CRUD + add/remove from docs
|
||||
- [x] Search
|
||||
- [x] 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 |
|
||||
Reference in New Issue
Block a user