@klevar/portal-cli

First-class npm CLI for the Klevar Client Management Portal.

Install

Run without installing:

npx @klevar/portal-cli help

Install globally for repeated use:

npm install -g @klevar/portal-cli
klevar-portal help

Configuration

Configuration is read from environment variables or ~/.klevar/portal.env.

PORTAL_API_URL=https://api.klevar.ai
PORTAL_API_KEY=cmp_live_replace_me
PORTAL_TOKEN=

PORTAL_API_URL defaults to http://127.0.0.1:3100 for local development. Use PORTAL_TOKEN only for client portal commands.

Do not paste API keys, portal tokens, or production secrets into chat logs, issue trackers, screenshots, or committed files.

Command Examples

npx @klevar/portal-cli health
npx @klevar/portal-cli tenant info
npx @klevar/portal-cli clients list
npx @klevar/portal-cli clients create --name "Stefan" --email "[email protected]" --platform direct
npx @klevar/portal-cli projects create <clientId> --name "Idealo" --externalRef "idealo:ksh.de"
npx @klevar/portal-cli metrics push --external_ref "idealo:ksh.de" --source_ref "run:33" --snapshot_date "2026-04-12" --metrics '{"score":88}'
npx @klevar/portal-cli portal me --portal-token "<client-token>"
npx @klevar/portal-cli portal search --query "maintenance" --portal-token "<client-token>"
npx @klevar/portal-cli portal tasks <projectId> --portal-token "<client-token>"
npx @klevar/portal-cli clients get <clientId> --json --compact
npx @klevar/portal-cli tasks create <projectId> --title "Task" --description-file tmp/task.md
npx @klevar/portal-cli tasks update <taskId> --description-file tmp/task.md
npx @klevar/portal-cli tasks get <taskId>

For multiline Portal Markdown, prefer --description-file for task descriptions and --content-file for updates/comments/notes. The CLI rejects literal escaped newlines like \n in client-visible Markdown fields.

portal my-tasks lists requests submitted by the client across projects. portal tasks <projectId> lists the tasks shown on that project detail page, including admin-created project tasks that are visible in the client portal.

Tasks And Milestones

Milestones are project-scoped. Tasks can be standalone or linked to one milestone by key, usually m0, m1, etc. Use klevar-portal milestones list <projectId> to see milestone keys and linked task counts before mutating data.

# Inspect milestones and linked task counts
npx @klevar/portal-cli milestones list <projectId>

# Show one milestone and its child tasks; accepts 1-based index or milestone key
npx @klevar/portal-cli milestones show <projectId> m0
npx @klevar/portal-cli milestones show <projectId> 3

# Add or update milestones
npx @klevar/portal-cli milestones add <projectId> --name "8. Launch readiness" --phase next --key m8
npx @klevar/portal-cli milestones update <projectId> m8 --phase current --status in_progress

# Create a new task directly under a milestone
npx @klevar/portal-cli tasks create <projectId> --title "Confirm API access" --description-file tmp/task.md --milestone m0 --priority high

# Read back one task with the stored Markdown description
npx @klevar/portal-cli tasks get <taskId>

# Link, move, or unlink an existing task
npx @klevar/portal-cli tasks link-milestone <taskId> m1
npx @klevar/portal-cli tasks update <taskId> --milestone m2
npx @klevar/portal-cli tasks unlink-milestone <taskId>

When task status changes, the parent milestone status is synced automatically:

• all linked tasks done → milestone becomes done;
• some linked tasks active/done/blocked → milestone becomes in_progress;
• no linked progress → milestone remains pending.

Backfill is a one-time migration helper for old task titles like M0: Confirm API access. Always dry-run first. It links matching tasks to milestone keys such as m0 and removes the textual prefix from the title. Non-prefixed tasks remain standalone.

npx @klevar/portal-cli milestones backfill-prefixes <projectId> --dry-run true
npx @klevar/portal-cli milestones backfill-prefixes <projectId> --confirm true

Milestone completion can optionally emit client notifications according to notification policy:

npx @klevar/portal-cli milestones done <projectId> 3 --note "Access pack complete" --notifyClient false
npx @klevar/portal-cli milestones undo <projectId> 3

Help is available globally and per resource:

npx @klevar/portal-cli help
npx @klevar/portal-cli help milestones
npx @klevar/portal-cli milestones --help
npx @klevar/portal-cli tasks --help

Capacity And Usage

Capacity commands manage included allowances for a project or client. They are not timesheets.

npx @klevar/portal-cli capacity list <projectId>
npx @klevar/portal-cli capacity create <projectId> --name "Monthly Support" --laneKey support --unitType hours --periodType monthly --startDate 2026-06-01 --capacityAmount 12 --resetBehavior no_rollover --visibility client_visible_summary
npx @klevar/portal-cli capacity update <budgetId> --capacityAmount 20
npx @klevar/portal-cli capacity summary <projectId> --period 2026-06
npx @klevar/portal-cli capacity budget-summary <budgetId> --period 2026-06
npx @klevar/portal-cli capacity report <projectId> --period 2026-06
npx @klevar/portal-cli capacity notifications <budgetId>
npx @klevar/portal-cli capacity notifications-update <budgetId> --notifyAtWarning true --warningThresholdPct 80 --notifyAtCap true --notifyOverCap true --notifyClient false --notifyAdmin true
npx @klevar/portal-cli capacity notification-state <budgetId> --period 2026-06
npx @klevar/portal-cli capacity pause <budgetId>
npx @klevar/portal-cli capacity resume <budgetId>
npx @klevar/portal-cli capacity end <budgetId>
npx @klevar/portal-cli capacity delete <budgetId>

For a temporary change, set the total for one month, including any rollover:

npx @klevar/portal-cli capacity override <budgetId> 2026-09 --totalCapacity 25 --reason "Temporary September increase"
npx @klevar/portal-cli capacity overrides <budgetId>
npx @klevar/portal-cli capacity override-remove <budgetId> 2026-09 --confirm

This leaves the recurring allowance unchanged. A 12-hour allowance with 6 rollover hours becomes 25 hours total for September. October uses the normal 12-hour allowance plus eligible ordinary rollover. Temporary extra hours expire at the end of September. Ordinary hours are consumed first, so if September uses 20 hours, October starts at 12. The month follows the budget's reset day. Overrides can also reduce the total, including to zero, and do not alter recorded usage. Use capacity update --capacityAmount only for recurring changes.

Usage commands record consumed capacity.

npx @klevar/portal-cli usage record <taskId> --budgetId <budgetId> --units 1.5 --usageDate 2026-06-03 --title "Maintenance support"
npx @klevar/portal-cli usage manual <projectId> --budgetId <budgetId> --units 1 --usageDate 2026-06-03 --title "Advisory call"
npx @klevar/portal-cli usage update <usageId> --units 2 --notes "Adjusted after review"
npx @klevar/portal-cli usage approve <usageId>
npx @klevar/portal-cli usage reject <usageId>
npx @klevar/portal-cli usage delete <usageId>

Current smoke-tested unitType values are hours and credits.

Supported periodType values:

• monthly: period keys use YYYY-MM.
• weekly: ISO week period keys use YYYY-Www, for example 2026-W23.

Supported visibility values:

• internal_only: hidden from client portal capacity APIs.
• client_visible_summary: client can see summary totals only.
• client_visible_detail: client can see summary totals and visible usage entries.

Capacity notification flags are writable on capacity create, capacity update, and capacity notifications-update:

• notifyAtWarning: default true.
• notifyAtCap: default true.
• notifyOverCap: default false.
• notifyOnReset: stored for future reset notifications; no scheduler is active yet.
• notifyClient: default false; client capacity emails require explicit opt-in and non-internal visibility.
• notifyAdmin: default true.
• warningThresholdPct: default 80.

Validation failures print API field details when the server returns them, for example:

Error 400: Validation failed
  periodType: Invalid option: expected one of "monthly"|"weekly"|...

Brain Usage

Brain usage should prefer the published npx @klevar/portal-cli entrypoint.

Brain agents should call:

npx @klevar/portal-cli <resource> <action> [id] [--key value]

The local compatibility wrapper remains available for old automation after a build:

npm run cli:build
klevar-portal clients list

New automation should use npx @klevar/portal-cli.

Auth Modes

• Admin and integration commands use X-API-Key.
• Portal commands use PORTAL_TOKEN or --portal-token.
• Public commands such as health checks and onboarding submission do not require credentials.

Explicit no-CLI exemptions are tracked in tools/commands/_exemptions.ts:

• POST /api/admin/login, POST /api/admin/logout, and GET /api/admin/me are browser/session-only routes.
• POST /api/tenants/register is public bootstrap/self-registration, not a normal operational CLI action.
• POST /api/integration/klevar-docs/events is an inbound webhook called by Klevar Docs.

npm Release Flow

The npm release flow is automated in GitHub Actions and can be dry-run locally.

Dry-run locally:

npm run cli:publish:dry

Manual publish:

npm run cli:publish

GitHub Actions also provides:

• .github/workflows/auto-publish-cli.yml: publishes from main when tools/** changes.
• .github/workflows/publish-cli.yml: manual or portal-cli-v*.*.* tag fallback.

Security Notes

Do not paste API keys into shell history on shared machines. Prefer ~/.klevar/portal.env with user-only file permissions or a secret manager. Rotate a key immediately if it appears in logs or commits.