TrueCal CLI

Official CLI package for scoped personal-agent access to TrueCal.

Current status: secure vertical slice. Browser PKCE login, device-code agent enrollment, named agent profiles, rotating agent refresh tokens, scoped executor calls, redacted audit listing, profile/health snapshots, and read/additive meal workflows are wired.

Agent-facing data contract: AGENT_API_REFERENCE.md.

Safe contract

• JSON output is available with --json.
• Agent mode must use --no-interactive.
• truecal api requires an api:raw grant and per-procedure allowlist approval.
• Mutating workflow commands require explicit meals:create, non-interactive mutation enablement, idempotency keys, and keychain-grade storage.
• This package has no runtime dependencies and no lifecycle scripts.
• The CLI stores credentials outside project directories and never prints tokens.

Commands

• truecal --help
• truecal help --json
• truecal auth login --json
• truecal auth refresh --profile <name> --json --no-interactive
• truecal auth status --json
• truecal auth logout --json
• truecal agent doctor --json
• truecal agent enable <profile> --json
• truecal agent enable <profile> --device --json
• truecal agent revoke <profile> --json
• truecal me --json
• truecal profile get --json
• truecal targets get --json
• truecal meals day --date YYYY-MM-DD --json
• truecal meals list --date YYYY-MM-DD --json
• truecal meals totals --start-date YYYY-MM-DD --end-date YYYY-MM-DD --json
• truecal meals log --input @meal.json --json
• truecal audit list --json
• truecal api <procedure> --json

Agent setup

truecal auth login --json
truecal agent enable codex --json
truecal auth refresh --profile codex --json --no-interactive
truecal me --profile codex --json --no-interactive
truecal profile get --profile codex --json --no-interactive

Headless fallback:

truecal agent enable codex --device --api-url https://app.truecal.com --json

The command prints a short code to stderr. The human approves it at /agent-cli/device; the CLI polls until the server returns the scoped agent credential bundle.

Scheduled jobs can run truecal auth refresh --profile <name> --json --no-interactive to rotate the stored agent token without a browser/device approval flow.

Mutation setup

truecal agent enable codex-writer --scope meals:create --allow-mutate --json
truecal meals log --profile codex-writer --input @meal.json --json --no-interactive

Mutation-capable profiles require OS keychain storage. File fallback stays degraded and read-oriented.