cli-anything-siyuan

¿Qué hace cli-anything-siyuan?

CLI para SiYuan (思源笔记), una aplicación de gestión de conocimiento y toma de notas centrada en el almacenamiento local.

Este CLI se conecta a un núcleo de SiYuan en ejecución a través de su API HTTP (http://127.0.0.1:6806) y proporciona acceso estructurado a cuadernos, documentos, bloques, búsqueda y exportación.

Prerrequisitos

• SiYuan debe estar en ejecución (Configuración → Acerca de muestra el token API)
• Python 3.10+
• Instalación: pip install cli-anything-siyuan o pip install -e . desde agent-harness/

Grupos de comandos

notebook — Gestión de cuadernos

Subcomando	Descripción
list	Listar todos los cuadernos
create <nombre>	Crear un nuevo cuaderno
rename <id> <nombre>	Renombrar un cuaderno
remove <id>	Eliminar un cuaderno
open <id>	Abrir un cuaderno

doc — Gestión de documentos

Subcomando	Descripción
create <cuaderno> <ruta> [--md "contenido"]	Crear un documento
list <cuaderno> [ruta]	Listar documentos
tree <cuaderno> [--path / --depth]	Mostrar árbol de documentos
get <id>	Obtener ruta del documento por ID
rename <id> <título>	Renombrar un documento
remove <id>	Eliminar un documento

block — Operaciones con bloques

Subcomando	Descripción
insert <datos> [--previous / --parent]	Insertar un bloque
update <id> <datos>	Actualizar un bloque
delete <id>	Eliminar un bloque
get <id>	Obtener código fuente kramdown del bloque
children <id>	Obtener bloques hijos

Otros comandos

Comando	Descripción
sql <sentencia>	Ejecutar SQL en la base de datos de bloques
search <consulta>	Búsqueda de texto completo en bloques
export md <doc-id>	Exportar documento como Markdown
tag list	Listar todas las etiquetas
version	Mostrar versión del núcleo de SiYuan
status	Mostrar estado de conexión y sesión
repl	Iniciar REPL interactivo

Guía para agentes

• Usa siempre --json para salida legible por máquina
• Búsqueda avanzada: usa sql "SELECT * FROM blocks WHERE content LIKE '%palabra%'" para acceso a nivel SQL
• Los IDs de documento tienen el formato 20210817205410-2kvfpfn (basado en timestamp)
• El token API se encuentra en Configuración de SiYuan → Acerca de
• Conexión predeterminada: http://127.0.0.1:6806

Ejemplos

# Listar cuadernos (JSON)
cli-anything-siyuan --json notebook list

# Crear un documento con Markdown (bandera --md, cuidado con el escape del shell)
cli-anything-siyuan doc create nb1 /projects/new --md "## Título\n\nContenido"

# Crear un documento — pasar Markdown por stdin (evita problemas de escape)
# PowerShell here-string (literal, sin necesidad de escapado):
@'
## Título
Contenido con `backticks`, (paréntesis) y "comillas"
'@ | cli-anything-siyuan doc create nb1 /projects/new --md -

# Bash heredoc:
# cat <<'EOF' | cli-anything-siyuan doc create nb1 /projects/new --md -
# ## Título
# Contenido con `backticks` y (paréntesis)
# EOF

# Búsqueda SQL
cli-anything-siyuan sql "SELECT id, content FROM blocks WHERE content LIKE '%reunión%' LIMIT 5"

# Exportar
cli-anything-siyuan export md doc123

# Iniciar REPL
cli-anything-siyuan

Manejo de errores

• Errores de conexión: verifica que SiYuan esté en ejecución y el token API sea correcto
• Errores de API: se devuelven como {"code": N, "msg": "..."} — verifica el campo msg
• Errores de autenticación: verifica el token en ~/.siyuan-cli.json o la variable de entorno SIYUAN_TOKEN