PlanillaSoft CLI (ps)

CLI para operar PlanillaSoft (nómina multi-tenant, Panamá) desde la terminal y desde agentes de IA (Claude Code, Codex, etc.). Acompaña a una Skill que enseña al agente a usarlo.

Instalación

Opción A — instalador de una línea (Mac/Linux):

curl -fsSL https://planillasoft.com/install.sh | bash

Detecta/instala Node.js si falta e instala el CLI.

Opción B — con npm (requiere Node.js ≥ 18):

npm install -g planillasoft-cli

Windows: instala Node desde https://nodejs.org y luego usa la Opción B.

Primeros pasos

# 1) Crea una API key en https://app.planillasoft.com → Integraciones → API keys
ps auth login --api-key psk_xxx.yyy     # las URLs de producción ya vienen por defecto
ps health && ps me
# 2) Fija tu empresa y plantilla:
ps company list && ps config set defaultCompanyId <id>
ps template list                        # copia el templateId
# 3) Ejecutar la planilla de una quincena:
ps run quickstart --template <templateId> --period-start 2026-06-01 --period-end 2026-06-15 --payment-date 2026-06-15

Por defecto el CLI usa https://api.planillasoft.com y https://app.planillasoft.com. Para otro entorno: ps config set apiBaseUrl/webBaseUrl, las env PLANILLASOFT_API_URL/PLANILLASOFT_WEB_URL, o el flag global --api-url (--web-url solo aplica a run export).

Para agentes de IA

Instala la Skill (skill/) en tu agente para operar PlanillaSoft en lenguaje natural. Ver skill/README.md.

Desarrollo

npm install
npm run build           # tsc -b -> dist/
npm test                # vitest (unit + integración)
node bin/run.js --help  # explora el árbol de comandos

Documentación

• Manual de usuario (no técnico) — integra PlanillaSoft con tu asistente de IA (también dentro de la app: menú → Integrar con IA).
• Empezar en 5 minutos (técnico) — instala, crea tu API key y ejecuta tu primera planilla.
• API keys y scopes (admins)
• Solución de problemas
• Publicar versiones (mantenedores) · Changelog
• Lanzamiento y beta · Roadmap v2
• Superficie de API v1 (endpoint → comando) · Contrato de salida y exit codes
• Decisiones de arquitectura · Plan de proyecto

Resumen

• Stack: TypeScript + oclif · paquete npm planillasoft-cli · binario ps (alias planillasoft).
• Auth: API keys propias de PlanillaSoft (Authorization: ApiKey <prefix>.<secret>).
• Multi-tenant: workspace + company explícitos (flag > env > config).
• Pensado para agentes: salida JSON estable y versionada, exit codes deterministas, guardas en operaciones sensibles.

Publicar una versión (mantenedores)

El CI publica a npm al subir un tag de versión:

npm version patch      # sube version en package.json y crea el commit+tag
git push && git push --tags

Requiere el secreto NPM_TOKEN configurado en el repo de GitHub. Ver docs/RELEASING.md.