@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>

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.