WebCull - Documentation - CLI de WebCull

Sinopsis

Referencia de comandos de CLI de WebCull

La CLI de WebCull es una herramienta de línea de comandos para encontrar, crear y actualizar marcadores desde una terminal o flujo de automatización. Los comandos devuelven JSON por defecto y están diseñados para trabajar con cuentas grandes de marcadores mediante límites, paginación, selección de campos y presupuestos de salida.

webcull <command> [options]

Comando

webcull

Paquete

@webcull/cli

Ruta de configuración

~/.config/webcull/config.json, o la ruta definida por WEBCULL_CONFIG.

URL de API

El valor predeterminado es https://api.webcull.com. Anúlelo con WEBCULL_API_URL.

Autenticación

Autorice la CLI antes de ejecutar comandos de cuenta

webcull login
webcull auth login
webcull whoami
webcull limits

webcull login inicia un flujo breve de aprobación en el navegador. La terminal muestra un código de emparejamiento, el navegador muestra el mismo código, y la aprobación crea un token de CLI para comandos de lectura y escritura de marcadores.

Apruebe solo un inicio de sesión que usted inició. Compare el código de la terminal con el código del navegador antes de aprobar.

login

Inicia la autorización del navegador y guarda el token de CLI después de la aprobación.

auth login

Alias de login.

whoami

Imprime la cuenta autorizada como JSON.

limits

Imprime los límites actuales de uso de CLI y la capacidad de solicitudes restante.

Comandos de lectura

Empezar amplio, luego obtener registros específicos de marcadores

webcull bookmarks count [--path <path>]
webcull bookmarks tree [--path <path>] [--max-depth <n>] [--per-parent-limit <n>]
webcull bookmarks search --query <query> [--sort <sort>]
webcull bookmarks get --ids <ids>

bookmarks count

Cuenta los elementos secundarios bajo una ruta de marcadores. La ruta predeterminada es /.

bookmarks tree

Devuelve un árbol acotado desde una ruta. Los valores predeterminados incluyen --limit 50, --max-depth 2 y --max-chars 12000.

bookmarks search

Busca metadatos de marcadores. El límite de resultados predeterminado es 25 y la ordenación predeterminada es modified_desc.

bookmarks get

Obtiene marcadores específicos por ID. Pase un ID, ID separados por comas o --ids.

Prefiera count o un tree superficial antes de obtener conjuntos de resultados más grandes. Use get después de conocer los ID de marcadores que necesita.

Controles de salida

Limitar tamaño de carga y elegir campos de salida

webcull bookmarks tree --path / --max-depth 1 --limit 25 --max-chars 8000 --fields id,type,title,modified
webcull bookmarks get --ids 123,456 --fields id,title,url,notes --max-metadata-chars 1500 --format json
webcull bookmarks search --query 'github api' --limit 20 --format jsonl

--limit <n>

Número máximo de resultados devueltos por comandos que listan marcadores.

--page <n>

Número de página para comandos que admiten resultados paginados. Las páginas empiezan en 1.

--max-chars <n>

Presupuesto máximo de tamaño de respuesta.

--max-metadata-chars <n>

Texto máximo de metadatos incluido para cada marcador.

--fields <list>

Campos de salida separados por comas, como id,title,url,parent_id,modified.

--format json|jsonl

Imprime JSON formateado por defecto. jsonl imprime un elemento por línea cuando la respuesta contiene una lista de elementos.

Búsqueda

Usar términos de consulta, filtros de campo y escaneos acotados

webcull bookmarks search --query 'github api'
webcull bookmarks search --query 'title:"github" AND notes:api'
webcull bookmarks search --query '(title:"github" OR url:"github.com") AND notes:api'
webcull bookmarks search --query 'github api' --limit 20 --max-scan-rows 500

Las cuentas en texto claro usan búsqueda del lado del servidor. Las cuentas cifradas usan automáticamente búsqueda local descifrada cuando se necesita buscar texto de marcadores.

E2EE search syntax

La búsqueda local descifrada admite términos simples, filtros de campo y AND. Las consultas locales complejas con OR y paréntesis se rechazan para la búsqueda local en cuentas cifradas.

--max-scan-rows <n>

Máximo de marcadores escaneados durante la búsqueda local descifrada. El comando limita este valor a 5000.

--page-size <n>

Número de marcadores revisados a la vez durante la búsqueda local descifrada. El comando limita este valor a 200.

--sort <sort>

Orden de clasificación para llamadas de búsqueda y escaneo. El valor predeterminado es modified_desc.

Comandos de escritura

Crear y actualizar marcadores

webcull bookmarks create --url <url> [--title <title>] [--notes <text>] [--tags <tags>] [--parent-id <id>] [--parent-path <path>] [--dry-run]
webcull bookmarks create --type folder --title <title> [--parent-id <id>] [--dry-run]
webcull bookmarks update <id> [--url <url>] [--title <title>] [--notes <text>] [--tags <tags>] [--parent-id <id>] [--parent-path <path>] [--dry-run]

--url <url>

Crea o actualiza una URL de marcador. Es obligatorio al crear un marcador.

--type folder

Crea una carpeta. Crear carpetas requiere --title y no acepta --url.

--title <title>

Define el título del marcador o carpeta.

--notes <text>

Define notas del marcador.

--tags <tags>

Define etiquetas separadas por comas. Se recorta el espacio alrededor de cada etiqueta.

--parent-id <id>

Coloca el marcador o la carpeta bajo un padre por ID.

--parent-path <path>

Coloca el marcador o la carpeta bajo un padre por ruta. No combine con --parent-id.

--dry-run

Valida autenticación, alcance, límites, propiedad, ubicación y estado E2EE sin guardar el cambio.

Los comandos de escritura preservan los campos no incluidos en el comando. No admiten escrituras por lotes, escrituras recursivas, creación automática de carpetas, conversión de marcador a carpeta, conversión de carpeta a marcador, carga de iconos ni flujos de activar, desactivar o cambiar clave E2EE.

Cuentas cifradas

Las frases de contraseña E2EE permanecen en avisos ocultos de terminal

En cuentas E2EE, la CLI pide la frase de contraseña E2EE solo mediante entrada interactiva oculta en la terminal. Nunca acepta frases de contraseña E2EE en argumentos, variables de entorno, archivos de configuración, tuberías stdin, registros o ejemplos.

Los campos cifrados de marcadores se cifran localmente antes de las escrituras y se descifran localmente para lecturas compatibles. El servidor recibe valores cifrados y nunca recibe frases de contraseña, claves derivadas, hashes de frases de contraseña ni campos de marcadores descifrados para validación E2EE.

Las escrituras de CLI se bloquean mientras la conversión E2EE está en curso. Termine la conversión E2EE en la app antes de actualizar marcadores que aún necesitan conversión.

Tokens

Los tokens de CLI son independientes de las sesiones del navegador

La CLI guarda su token en ~/.config/webcull/config.json por defecto con modo de archivo 0600. Defina WEBCULL_CONFIG para usar otra ruta.

El token es independiente de las sesiones de navegador y extensión. Los tokens actuales de CLI para marcadores incluyen bookmarks:read y bookmarks:write.

Límites

Usar límites como guía de ritmo

WebCull limita solicitudes de CLI para proteger cuentas y mantener el servicio ágil. Los comandos de lectura y escritura tienen límites diferentes.

Token de lectura

60 solicitudes por minuto, 600 por hora y 3000 por día.

Usuario o IP de lectura

Los límites de usuario e IP proporcionan protección adicional de cuenta y red.

Token de escritura

10 solicitudes por minuto, 100 por hora y 500 por día.

Usuario o IP de escritura

Las solicitudes de escritura tienen un ritmo de cuenta y red más estricto que las solicitudes de lectura.

Consulta de límites

7 solicitudes por minuto. Use webcull limits con moderación.

Ante una respuesta limitada, espere al menos 60 segundos antes de reintentar. Reduzca la siguiente solicitud cuando sea posible. Las escrituras de prueba usan el límite de escritura porque ejercitan la ruta de escritura y las comprobaciones de propiedad.