CreamPhase CLI

CreamPhase is the agent-first JSON protocol client for the private CreamPhase topical treatment tracker.

Install

npm install -g creamphase

Configure

For local operator setup, store the private token without putting the secret in the command arguments:

printf '%s' "$CREAMPHASE_API_TOKEN" | creamphase login --token-stdin
creamphase status

The CLI stores config at ~/.config/creamphase/config.json with user-only file permissions on POSIX systems. Agents should usually skip stored config and use CREAMPHASE_API_TOKEN plus optional CREAMPHASE_API_URL. login --token <token> remains available for one-off setup, but --token-stdin is preferred because command arguments can end up in shell history or process listings.

Agent Protocol

Use command discovery first, then call the Convex-backed protocol command:

creamphase commands
creamphase schema treatment.start
creamphase call status --input-json '{}'
creamphase call today --input-json '{"today":"2026-04-23"}'

Use --dry-run before risky writes, and reuse --request-id only when retrying the exact same write:

creamphase call treatment.end --input-json '{"treatment_id":"<treatment-id>","end_reason":"stopped_early","cutoff_date":"2026-04-23","confirm":"END:<treatment-id>"}' --dry-run --request-id agent-123
creamphase call treatment.end --input-json '{"treatment_id":"<treatment-id>","end_reason":"stopped_early","cutoff_date":"2026-04-23","confirm":"END:<treatment-id>"}' --request-id agent-123

Protocol/operator command output is a stable JSON envelope: { ok, data|error, warnings, requestId, protocolVersion }. Standard --help and --version remain conventional CLI metadata. There are no interactive prompts and no domain wrapper commands; operations such as today, slot.set, treatment.start, and delete-all are available only through creamphase call.

Date-bearing commands require explicit local yyyy-mm-dd dates from the agent. In particular, treatment.end requires cutoff_date; never omit it and let the server infer a date.

Remote calls use a 30-second request timeout and return a structured NETWORK_ERROR if the API stalls. For update commands, omitted optional fields preserve the current value; send an empty string for optional text fields, an empty array for replace-all list fields, or maintenance: null when you intentionally want to clear them. The dedicated treatment.notes command also accepts notes: "" to clear notes. For create commands, optional list fields may be omitted or sent as an empty array.

slot.set is an all-or-error single-slot command: stale, voided, ended-treatment, or missing slots return an error envelope. Use slot.bulk only when you intentionally want per-slot partial-success results.

For cream phase edits, omit id when creating a new phase. Existing phase ids must be non-empty strings; do not send id: "" or id: null. Cream maintenance is optional reference-only metadata, separate from slot-generating phases. If present, it is finite and uses { "frequency_type": "per_day" | "per_week", "frequency_value": <positive integer>, "duration_weeks": <positive integer> }.

Destructive commands require exact confirmations such as DELETE_ALL_DATA, END:<treatmentId>, DELETE:<treatmentId>, or ARCHIVE:<id>. delete-all also clears CLI request logs and is not written back into the idempotency log after it succeeds.

Environment Overrides

• CREAMPHASE_API_URL overrides the configured API URL.
• CREAMPHASE_API_TOKEN overrides the stored token.
• CREAMPHASE_OUTPUT=json is accepted for compatibility; protocol/operator commands already emit JSON.
• CREAMPHASE_NO_INPUT=1 is accepted for compatibility; prompts do not exist.