CLI

chronacta is a gRPC client. It does not open the storage directory directly.

Stream commands

./bin/chronacta health [-server ADDRESS] [-json]
./bin/chronacta append -stream ID -type TYPE -data JSON [-expected-version N] [-idempotency-key KEY]
./bin/chronacta read -stream ID [-from VERSION] [-count N] [-backward]
./bin/chronacta read-all [-from POSITION] [-count N]
./bin/chronacta subscribe -stream ID [-from VERSION]
./bin/chronacta verify
./bin/chronacta verify-db
./bin/chronacta stream-info -stream ID
./bin/chronacta stream list [-prefix PREFIX] [-page-size N] [-page-token TOKEN]
./bin/chronacta storage-status
./bin/chronacta stream-size -stream ID

Schema commands

./bin/chronacta schema register -name NAME -version N -file schema.json [-compatibility none|backward|forward|full]
./bin/chronacta schema get -name NAME -version N
./bin/chronacta schema list
./bin/chronacta schema validate -name NAME -version N -data JSON

Integration commands

Export committed events to JSONL and import them into another stream or cluster. Export requires stream.read; import requires stream.append.

./bin/chronacta export stream -stream ID [-from VERSION] [-output FILE] [-format jsonl|binary]
./bin/chronacta export all [-from POSITION] [-output FILE] [-format jsonl|binary]
./bin/chronacta import -file FILE [-format auto|jsonl|binary] [-dry-run] [-duplicate-policy POLICY]

Duplicate policies for import:

• reject_existing_stream (default) — fail if the target stream already exists before import starts
• append — append with ExpectedVersionAny
• skip_by_event_id — skip records whose source_event_id is already present

See Export/import, NATS bridge, and Duplicate policy.

NATS bridge operations:

./bin/chronacta integration nats status [-server ADDRESS] [-json]
./bin/chronacta integration nats replay [-from POSITION] [-json]

Cluster commands

Cluster metadata, replication lag, and leader-only membership operations. Requires verify permission when auth is enabled. Membership mutations require connecting to the cluster leader.

./bin/chronacta cluster status [-server ADDRESS] [-json]
./bin/chronacta cluster status -node [-json]
./bin/chronacta cluster add-node -node-id ID -addr HOST:PORT [-role follower|learner]
./bin/chronacta cluster remove-node -node-id ID
./bin/chronacta cluster promote -node-id ID
./bin/chronacta cluster snapshot push -target-node-id ID

See HA rolling upgrade and Replication architecture.

Backup commands

./bin/chronacta backup create [-archive PATH] [-dry-run]
./bin/chronacta backup list [-dir ./backups]
./bin/chronacta backup inspect -archive PATH

Offline restore remains in chronacta-admin restore --archive PATH --target DIR --confirm.

Durable subscription commands

At-least-once semantics: duplicates are normal until consumers are idempotent.

./bin/chronacta subscription create -id SUB -stream STREAM [-consumer NAME] [-start N]
./bin/chronacta subscription list
./bin/chronacta subscription get -id SUB
./bin/chronacta subscription delete -id SUB
./bin/chronacta subscription pull -id SUB [-max N]
./bin/chronacta subscription ack -id SUB -position GLOBAL
./bin/chronacta subscription nack -id SUB -position GLOBAL [-reason TEXT]
./bin/chronacta subscription pause -id SUB
./bin/chronacta subscription resume -id SUB
./bin/chronacta subscription replay -id SUB [-from N]
./bin/chronacta subscription dead-letters [-id SUB]

Consumer group commands

Fan-out partition: each member receives events where global_position % N == member_index.

./bin/chronacta consumer-group create -id GROUP -stream STREAM
./bin/chronacta consumer-group join -id GROUP -member MEMBER
./bin/chronacta consumer-group leave -id GROUP -member MEMBER
./bin/chronacta consumer-group list
./bin/chronacta consumer-group get -id GROUP

See Consumer groups.

Projection commands

./bin/chronacta projection create -name NAME -runtime builtin|cel|starlark -program CODE \
  [-source-stream STREAM|$all] [-event-types a,b] [-filter CEL] [-initial-state JSON]
./bin/chronacta projection list
./bin/chronacta projection get -name NAME
./bin/chronacta projection status -name NAME
./bin/chronacta projection state -name NAME
./bin/chronacta projection result -name NAME
./bin/chronacta projection enable -name NAME
./bin/chronacta projection disable -name NAME
./bin/chronacta projection rebuild -name NAME [-from POSITION]
./bin/chronacta projection restore-checkpoint -name NAME -checkpoint POSITION
./bin/chronacta projection errors -name NAME
./bin/chronacta projection delete -name NAME

Built-in programs: count, count_by_type, sum_field, latest_by_key, group_count.

Optional -filter accepts a CEL expression returning bool, for example: event.event_type == "OrderPaid".

Additional operations:

./bin/chronacta projection resume -name NAME
./bin/chronacta projection verify-checkpoint -name NAME
./bin/chronacta projection migrate -name NAME -version N [-program CODE] [-migration-program CODE] [-rebuild] [-from N]
./bin/chronacta projection detect-stalled
./bin/chronacta projection dead-letters [-name NAME]

Postgres read-model SQL generator

YAML schema (owned by the query team) → DDL migrations and parameterized DML. Runtime does not create tables.

./bin/chronacta sqlgen generate ddl -schema SCHEMA.yaml -out migrations/
./bin/chronacta sqlgen generate dml -schema SCHEMA.yaml -out generated/

See postgres-projections.md and examples/postgres-projector/.

Auth commands

./bin/chronacta auth bootstrap -username admin -password SECRET
./bin/chronacta auth login -username USER -password SECRET
./bin/chronacta auth create-user -username USER -password SECRET [-roles a,b]
./bin/chronacta auth list-users
./bin/chronacta auth disable-user -username USER
./bin/chronacta auth set-password -username USER -password SECRET
./bin/chronacta auth create-role -name ROLE [-permissions p1,p2]
./bin/chronacta auth grant -role ROLE -permission PERM
./bin/chronacta auth revoke -role ROLE -permission PERM
./bin/chronacta auth list-roles
./bin/chronacta auth audit [-limit 100]

Common flags

Every network command accepts:

• -server gRPC address (default 127.0.0.1:2113)
• -token bearer token when auth is enabled
• -json for JSON output
• -tls, -tls-ca, -tls-cert, -tls-key, -tls-server-name for TLS

Errors go to stderr and return a non-zero exit code.

chronacta-cli and chronacta-admin forward supported commands to the same binary.