Causet CLI

The causet CLI builds, deploys, and operates apps on Causet — local or Cloud.

Backend model:

org → platform → app → fork → release / deploy / runtime

Install

curl -fsSL https://install.causet.io/install.sh | bash
causet version

The installer places causet on your PATH. Commands that compile locally (causet build, causet build compile) invoke the causet-compiler binary (bundled or resolved via CAUSET_COMPILER).

Shell completions:

causet completion bash   # or zsh, fish

Quick paths

Local (recommended for first retrofit)

causet local up
causet context use env local
 
causet init hello-causet --template concert-app --yes
cd hello-causet
causet build
causet deploy --fork sandbox --yes

Local context does not require causet login. API default: http://localhost:8085.

Causet Cloud

causet login
causet context show
 
causet init my-app --yes
cd my-app
causet build
causet plan --fork sandbox
causet deploy --fork sandbox

Request Cloud access at causet.io. Dashboard: cloud.causet.io.

Command groups

Group	Commands
Project	`new`, `templates`, `init`, `dev`, `build`, `plan`, `deploy`
Runtime	`intent`, `query`, `queries`, `inspect`, `watch`
Cloud	`login`, `logout`, `context`, `dashboard`, `orgs`, `platforms`, `apps`, `usage`
Operations	`release`, `fork`, `webhook`, `api-keys`, `secrets`, `recovery`, `forensics`, `projection`
Utilities	`local`, `doctor`, `about`, `completion`, `version`

causet --help
causet help advanced

Local runtime

Runtime files live under ~/.causet/local/.

causet local install   # Download compose stack from install.causet.io
causet local up        # Start stack (auto-installs if needed)
causet local status    # Containers + API readiness
causet local logs      # Tail logs (-f to follow)
causet local down      # Stop (keeps volumes)
causet local restart   # Restart, keep data
causet local reset --yes   # Wipe local state (destructive)

After up:

causet context use env local

Manual compose (advanced):

curl -fsSL https://install.causet.io/docker-compose.yml -o docker-compose.yml
docker compose up -d
causet context use env local

causet login                 # Hosted Cloud (Clerk OAuth)
causet login --token $CAUSET_TOKEN
 
causet context show
causet context use org <org_id>
causet context use platform <slug>
causet context use app <slug>
causet context use fork sandbox
causet context use env local     # or sandbox | prod

Config sources:

Source	Purpose
`~/.causet/config.json`	Session, org/platform/app/fork, cloud target
`.causet/causet.yaml`	Project defaults
`CAUSET_API_URL`	Override management API base (default local `http://localhost:8085`)
`CAUSET_QUERY_URL`	Direct query service HTTP (container port 8082). `causet query` routes via the management API — you usually do not need this unless calling query HTTP directly. Scaffolded `.env.example` from `causet init` may still show `8086`; prefer 8082 or omit and use `causet query`.
`CAUSET_CLOUD_URL`	Override control-plane UI
`CAUSET_COMPILER`	Path to `causet-compiler`

Project: init, build, plan, deploy

Scaffold

causet templates list
causet new event-driven-app my-event-app
causet init support-agent --template ai-support-agent --yes

Build (local, no runtime required)

causet build                 # lint → validate → compile
causet build validate
causet build compile --runtime ./causet --out dist
causet dev                   # watch + recompile

Plan (side-effect free)

causet plan --fork sandbox
causet plan --from-release 1.0.0 --to local --fork main

Deploy (golden path)

causet deploy runs:

build lint → validate → compile → plan →
release create → publish → deploy apply → activate

causet deploy --fork sandbox --yes
causet deploy --fork main --full
causet deploy --fork canary --canary --streams refund_stream

Runtime: intents, queries, inspect

Submit an intent

causet intent REFUND_REQUESTED \
  --stream refund_stream \
  --entity rfnd_123 \
  --payload '{"refund_id":"rfnd_123","order_id":"ord_1002","customer_id":"cus_1","amount":50,"reason":"damaged","requested_at":"2026-07-15T12:00:00Z"}' \
  --fork sandbox

Accepted output includes a timeline id (not a decision id).

Query

causet queries list
causet query refund_timeline_by_id --param refund_id=rfnd_123

Inspect

causet inspect                                    # interactive
causet inspect state --stream refund_stream --fork sandbox
causet inspect entity rfnd_123 --stream refund_stream --fork sandbox
causet inspect events --stream refund_stream --fork sandbox
causet inspect timeline --entity rfnd_123 --stream refund_stream --fork sandbox
causet inspect timeline-item <timeline-id>
causet inspect event REFUND_COMPLETED
causet inspect projection refund_timeline
causet inspect query refund_timeline_by_id

inspect state shows current entity snapshots; inspect timeline shows committed steps; inspect events lists domain events for a stream/fork.

Watch

causet watch --stream refund_stream --fork sandbox

Webhooks

causet webhook add \
  --name "Refund completion" \
  --url https://your-app.example/api/webhooks/causet/refunds \
  --events event:REFUND_COMPLETED,event:REFUND_FAILED \
  --fork sandbox

Use this to push Causet state changes back into your existing DB. See Webhooks.

Forks and recovery

causet fork list
causet fork create refund-debug --parent sandbox
causet fork diff sandbox refund-debug
 
causet recovery replay --stream refund_stream
causet recovery rewind --entity rfnd_123 --to-timeline <n>
causet recovery repair plan
causet forensics replay-check

Doctor

causet doctor
causet doctor --json

Checks (from shipped CLI):

Check	What it validates
CLI version	Installed `causet` version
Compiler binary	Native compiler resolves
Auth token	Skipped for local context; required for Cloud
Platform / application / fork	Effective CLI context
Project config	`.causet/causet.yaml` when present
Environment	`local`, `sandbox`, or `prod`
Realtime reachable	Realtime service HTTP (local default `http://localhost:8081`)
API reachable	Management API (`CAUSET_API_URL`, local default `http://localhost:8085`)

causet doctor does not probe the query service directly. Use causet query (via management API) or curl http://localhost:8082/actuator/health for the query container.

Retrofit loop (end to end)

Typical path for Retrofit an Existing App:

curl -fsSL https://install.causet.io/install.sh | bash
causet version
 
causet local up
causet context use env local
 
# In your workflow project (e.g. examples/retrofit-commerce)
causet build compile --runtime causet --out dist
causet deploy --fork sandbox --yes
 
# Hit your existing endpoint → then:
causet inspect timeline --entity <id> --stream refund_stream --fork sandbox
causet webhook add --name "Refund completion" --url http://localhost:3001/api/webhooks/causet/refunds \
  --events event:REFUND_COMPLETED,event:REFUND_FAILED --fork sandbox

JSON and CI

Most commands accept --json for machine-readable output. Set CI=1 to disable prompts.

github.com/Causet-Inc/causet-sdks — official SDKs
Install Causet
Retrofit an Existing App
Runtime options
What runs today?
Deployments

Runtime options Overview