Chel: Chelonia Command-line Interface

Modern CLI for Chelonia contract development, deployment, and management.

All Available Commands

chel
chel help [command]
chel version
chel pin [--dir <output-directory>] [--overwrite] <manifest-file-path> <version>
chel test
chel init [--force]
chel keygen [--out=<key.json>]
chel manifest [-k|--key <pubkey1> [-k|--key <pubkey2> ...]] [--out=<manifest.json>] [-s|--slim <contract-slim.js>] [-V|--contract-version <version>] <key.json> <contract-bundle.js>
chel deploy <url-or-dir-or-sqlitedb> <contract-manifest.json> [<manifest2.json> [<manifest3.json> ...]]
chel upload <url-or-dir-or-sqlitedb> <file1> [<file2> [<file3> ...]]
chel serve [options] <directory>
chel latestState <url> <contractID>
chel eventsAfter [--limit N] [--url <url>] [--keys <file>] <contractID> <height>
chel hash <file>
chel migrate --from <backend> --to <backend> [--from-config <from-config.toml>] [--to-config <to-config.toml>]

Note: in many (if not all) instances, the <url> parameter can refer to a local folder path, in which case the command will operate without making a network connection, and will instead use the folder's contents to perform its operations.

`chel pin` - Per-Contract Versioning System

🎯 Pin individual contracts to specific versions independently!

Key Features:

✅ Per-contract versioning using chelonia.json configuration
✅ Individual contract pinning by specifying manifest file path
✅ New directory structure: contracts/<contract-name>/<version>/
✅ Manifest-based workflow - requires existing manifest files
✅ Ecosystem-agnostic - no coupling to Node.js/npm

Workflow:

Generate keys: Use chel keygen to create cryptographic key files (required for production)
Pin from manifest: Use chel pin with the manifest file path
Contract files copied: Contract files (main/slim) and manifest are copied to new structure

Usage Examples:

# First, generate cryptographic keys (required for production)
chel keygen

# Then pin contracts with re-signing`
chel pin <manifest-file-path> <version>

# Pin specific contract to a version using its manifest (from dist/contracts)
chel pin 2.0.5 dist/contracts/2.0.5/chatroom.2.0.5.manifest.json
chel pin 2.0.0 dist/contracts/2.0.0/group.2.0.0.manifest.json

# Note: Contracts are pinned to the contracts/ output directory

Configuration (chelonia.json):

{
  "contracts": {
    "gi.contracts/chatroom": {
      "version": "2.0.6",
      "path": "contracts/gi.contracts_chatroom/2.0.6/chatroom.2.0.6.manifest.json"
    },
    "gi.contracts/group": {
      "version": "2.0.0",
      "path": "contracts/gi.contracts_group/2.0.0/group.2.0.0.manifest.json"
    }
  }
}

Directory Structure Created:

contracts/
├── gi.contracts_chatroom/
│   ├── 2.0.5/
│   │   ├── chatroom.js
│   │   └── chatroom-slim.js
│   └── 2.0.6/
│       ├── chatroom.js
│       └── chatroom-slim.js
└── gi.contracts_group/
    └── 2.0.0/
        ├── group.js
        └── group-slim.js

Command Options:

--overwrite: Force overwrite existing versions
Default: Create new version by copying from source

`chel init` - Generate `chel.toml`

Generates a template chel.toml in the current directory, pre-populated with sensible defaults and a freshly-generated server_id. This is the recommended way to bootstrap a new server instance.

chel init [--force]

Options:

--force: Overwrite an existing chel.toml. Without this flag, chel init refuses to clobber an existing file — a safety against accidentally rotating server_id, which would orphan push subscriptions tagged with the old id (see chel.toml).

What it writes:

A top-level server_id (a random UUID). Keep this stable for the lifetime of the database; do not reuse it across environments (prod / staging / dev) that share a database.
[server] / [database] blocks mirroring the defaults from parseConfig.ts, with less-common options left as commented-out lines for guidance.

Example:

$ chel init
wrote: chel.toml
server_id: 7b3f2c1a-... keep this stable; do not reuse across environments,
                        and do not rotate it on an existing DB.

`chel serve` - Development Server with Contract Preloading

chel serve [options] <directory>

OPTIONS

--dashboard-port <port>  set dashboard port (default: 8888)
--port           <port>  set application port (default: 8000)
--dev                    start in development mode (watch and redeploy contract manifests)

Important

Prerequisites: Ensure your application directory contains a contracts/ directory with the correct contract structure before running chel serve. The server automatically preloads all contract manifests found in contracts/<contract-name>/<version>/ directories into the database on startup in development mode.

Example Output:

$ chel serve
🚀 Starting Chelonia app server...
📦 Step 1: Preloading contracts...
📋 Found 4 contract manifest(s) to deploy
contracts/gi.contracts_chatroom/2.0.6/chatroom.js: /data/zLAeVmpcc88g...
contracts/gi.contracts_group/2.0.0/group.js: /data/zLAeVmpcc88g...
✅ Successfully preloaded 4 contract(s) into database
🚀 Step 2: Starting dashboard server...
📊 Dashboard server running at: http://localhost:8888
🚀 Step 3: Starting application server...

Usage Examples:

# Start with automatic contract preloading
chel serve

# Serve Group Income app from extracted directory
chel serve ./gi-v2.0.0

# Serve with custom ports and SQLite database
chel serve --dashboard-port 8888 --port 8000 ./my-app

What happens during startup:

Contract Discovery - Scans contracts/<name>/<version>/ directories
Manifest Collection - Finds all .manifest.json files
Database Preloading - Deploys all contracts with content-addressed storage
Server Startup - Starts dashboard and application servers
Ready for Development - All historical contracts available for message processing

`chel keygen`

{
  "version": "1.0.0",
  "cipher": "algo",
  "pubkey": "...",
  "privkey": "...",
  "encrypted": "algo"
}

If "encrypted" doesn't exist - it means the "privkey" was saved in the clear.

`chel serve`

Starts a local development server for Chelonia applications.

chel serve [options] <directory>

OPTIONS

--dashboard-port <port>    set dashboard port (default: 8888)
--port           <port>    set application port (default: 8000)

Example:

# Serve Group Income app from extracted directory
chel serve ./gi-v2.0.0

# Serve with custom ports and SQLite database
chel serve --dashboard-port 8888 --port 8000 ./my-app

The serve command will:

Start a dashboard server (default: http://localhost:8888)
Start an application server (default: http://localhost:8000)
Serve static assets and handle API routes
Support different database backends (memory, filesystem, SQLite, Redis)

`chel manifest`

Let's say you have the following files:

contract-bundle.js
contract-slim.js

Running chel manifest --add-key alex.json --slim contract-slim.js deploy-key.json contract-bundle.js will generate the following contract-bundle.manifest.json:

{
  "head": {
    "manifestVersion": "1.0.0"
  },
  "body": JSON.stringify({
    "version": "<contract version string, 'x'> by default",
    "contract": { "hash": "<hash of contract-bundle.js>", "file": "contract-bundle.js" },
    "contractSlim": { "hash": "<hash of contract-slim.js>", "file": "contract-slim.js" },
    "authors": [
      {"cipher": "algo", "key": "<pubkey from deploy-key.json>"},
      {"cipher": "algo", "key": "<pubkey from alex.json>"}
    ]
  }),
  "signature": {
    "key": "<which of the 'authors' keys was used to sign 'body'>",
    "signature": "<signature>"
  }
}

It will upload both versions of the contracts, and this JSON.

This format makes it as efficient as possible for using the contract system from both in-app and from the commandline.

The CLI tool will always use the self-contained contract bundle, whereas apps can load less code by loading the slim version of the contract. You just need to make sure that none of the external dependencies that you're referencing ever change if you do this, as otherwise you will get different state between the two versions of the contracts.

Note also that Chelonia is fundamentally language agnostic. We started out using Chelonia to build JS apps, but you can use this protocol with any programming language that supports source evaluation at runtime.

Some commands of this CLI tool (like latestState), only support JavaScript, but that is a limitation of resources on our side, and not a fundamental limitation of the protocol.

`chel deploy`

Deploys manifest(s) generated with chel manifest.

Automatically uploads any corresponding contract files.

Outputs the hash(es) corresponding to the manifest(s).

Useful command:

cp -r path/to/contracts/* test/assets/ && ls ./test/assets/*-slim.js | sed -En 's/.*\/(.*)-slim.js/\1/p' | xargs -I {} ./src/main.ts manifest --out=test/assets/{}.manifest.json --slim test/assets/{}-slim.js key.json test/assets/{}.js && ls ./test/assets/*.manifest.json | xargs ./src/main.ts deploy http://127.0.0.1:8888

`chel eventsAfter`

Displays a JSON array of events that happened in a given contract since a given height. Older events come first. The output is parseable with tools like jq.

chel eventsAfter [--limit N] [--url <url>] [--keys <keys.json>] <contractID> <height>

If --url is supplied, the remote server's /eventsAfter endpoint is queried. Otherwise, the local database (configured via chel.toml) is read directly.

Decrypting events with `--keys`

By default, encrypted events (OP_ACTION_ENCRYPTED and friends) are returned as opaque envelopes — useful for forensics, but unreadable. Pass --keys with a JSON file of secret keys to decrypt them in place.

Current limitation: decryption only works when the returned event list starts with the contract's OP_CONTRACT event (for example, by querying from height 0). If you query from a later height, decryptOne has no prior contract/key state, so encrypted events are returned as raw envelopes with no prior contract state rather than being decrypted.

Warning: this file contains secret key material and grants decryption capability for any events encrypted to those keys. Do not commit it to version control, include it in logs, or share it casually. Store it with restrictive file permissions, use it only for local debugging, and delete or otherwise protect it when you are done.

The file is a flat object mapping each keyId to its serialized secret key:

{
  "z9brR...sigKeyId": "<serializedSecretKey>",
  "z9brR...encKeyId": "<serializedSecretKey>"
}

This is exactly the shape Chelonia stores at rootState.secretKeys in any app built with libcheloniajs. The easiest way to generate this file is from a running app:

In a browser DevTools console (with the app open):

copy(JSON.stringify(await sbp('chelonia/rootState').secretKeys, null, 2))
// then paste into keys.json

Example:

chel eventsAfter --keys ./keys.json <contractID> 0 --limit 10

When --keys is supplied each event is emitted as:

{
  "height": 1,
  "hash": "z9brR...",
  "contractID": "z9brR...",
  "op": "ae",
  "signingKeyId": "z9brR...",
  "innerSigningKeyId": "z9brR...",
  "decryptedValue": { /* the inner contract action payload */ },
  "raw": {
    "serverMeta": {
      "date": "2025-06-09T20:35:43.305Z",
      "isKeyOp": true
    },
    "message": "{...}"
  }
}

Decryption is best-effort: if the required key is missing or a signature cannot be verified, the event is still emitted with the original envelope under raw, and decryptedValue may be absent or undefined. Some failure cases may also include a per-event error and/or print a one-line warning to stderr, but that is not guaranteed for every decryption failure.

`chel migrate`

Performs a non-destructive migration from one backend (--from) to another one (--to). For example, this can be used to migrate from the fs backend to the sqlite backend.

Since some backends may require additional configuration, chel migrate allows for specifying additional options for these backends with the --from-config and --to-config options.

By default, the general chel configuration will be used both for the --from and --to backends (such as the values given in chel.toml). However, if --from-config or --to-config are specified, those will take precedence.

The configuration files for --from-config and --to-config follow the same syntax and structure as chel.toml. This makes it easy to migrate to a new backend by writing a new chel.toml for that backend.

Examples

# Migrate from sqlite to redis using default values (possibly overridden in chel.toml)
chel migrate --from sqlite --to redis

# Migrate from sqlite to redis using default values (possibly overridden in chel.toml)
# for redis and the configuration in sqlite.toml for sqlite
chel migrate --from sqlite --from-config sqlite.toml --to redis

# Migrate from sqlite to redis using default values (possibly overridden in chel.toml)
# for sqlite and the configuration in redis.toml for redis
chel migrate --from sqlite --to redis --to-config redis.toml

# Migrate from sqlite to redis using the configuration in sqlite.toml for sqlite
# and the configuration in redis.toml for redis
chel migrate --from sqlite --from-config sqlite.toml --to redis --to-config redis.toml

Configuration Files

The project uses two separate configuration files for different purposes:

`chel.toml` — Runtime CLI Configuration

chel.toml configures the chel command itself at runtime. It is read by nconf with priority: CLI arguments > environment variables > chel.toml > defaults. It controls things like server host/port, database backend selection, and other operational settings.

# Example chel.toml
[server]
host = "0.0.0.0"
port = 8000
dashboardPort = 8888

[server.vapid]
email = "admin@example.com"

[database]
backend = "sqlite"

`chelonia.json` — App Properties

chelonia.json is an app-level properties file that describes which contracts make up the application and their pinned versions. It is not runtime configuration for chel. Instead, it is:

Created and updated by chel pin when pinning contracts to specific versions.
Read by the server (chel serve) at startup to provide version information and other app-specific settings to clients.

The file contains a contracts object keyed by the full contract name (e.g. gi.contracts/chatroom), where each entry has:

Field	Description
`version`	The pinned version string for this contract
`path`	Relative path to the manifest file in the `contracts/` directory

It may also contain an appVersion field for the overall application version.

Example:

{
  "appVersion": "2.0.0",
  "contracts": {
    "gi.contracts/chatroom": {
      "version": "2.0.6",
      "path": "contracts/gi.contracts_chatroom/2.0.6/chatroom.2.0.6.manifest.json"
    },
    "gi.contracts/group": {
      "version": "2.0.0",
      "path": "contracts/gi.contracts_group/2.0.0/group.2.0.0.manifest.json"
    }
  }
}

Summary of differences:

	`chel.toml`	`chelonia.json`
Purpose	Runtime configuration of the `chel` CLI	App properties (e.g., contract versions)
Managed by	Manually by the developer / system administrator	Automatically by `chel pin`
Read by	`chel` commands (via `nconf`)	The server (at startup), values exposed to clients
Format	TOML	JSON
Example content	Database configuration	Contract versions

Supported Platforms

Pre-compiled native binaries are published for the following platforms:

OS	Architecture	npm sub-package
Linux	x64	`@chelonia/cli-x64-linux`
Linux	arm64	`@chelonia/cli-arm64-linux`
Windows	x64	`@chelonia/cli-x64-win32`
macOS	x64 (Intel)	`@chelonia/cli-x64-darwin`
macOS	arm64 (Apple Silicon)	`@chelonia/cli-arm64-darwin`

When you install @chelonia/cli, npm automatically selects the correct sub-package for your platform via optionalDependencies. Windows arm64 is currently not supported.

Packaging

Steps to publish a new release of @chelonia/cli to npm:

Login to npm (prerequisite):
```
npm login
```
If your account uses 2FA, npm publish may prompt for authentication. Do not rely on --otp=<code>: the publish step compiles all five native binaries before publishing the first sub-package. Compilation is usually fast but can take several minutes, so a TOTP code entered at the start will likely have expired by the time the first npm publish runs. Complete the browser-based authentication flow when prompted, or use a granular automation token instead.
Bump the version:
```
npm version patch   # or minor / major
```
This triggers the version lifecycle hook, which runs after the version is bumped but before npm version commits and tags. The hook:
- Runs deno task sync-versions to update optionalDependencies in package.json so they match the new version (and stages the change)
- Runs deno task build to rebuild the JS bundle (stamped with the new version in build/version.json) and the dashboard
- Stages the rebuilt build/ artifacts
As a result, the version commit and tag contain the up-to-date bundle and the working directory stays clean. The publish step verifies that what it compiles is exactly this committed bundle and refuses to run otherwise. This also guarantees the maintainer rebuilds the bundle on master (merged PRs can each produce a correct bundle individually, yet the combined result on master may still differ).
Publish:
```
npm publish --access public
```
This triggers the prepublishOnly hook, which runs deno task publish. That script:
- Verifies that the committed bundle matches package.json (via build/version.json) and that the working tree is clean for build/ and package.json, refusing to publish otherwise
- Compiles a native binary for each supported platform from the committed build/ bundle (the bundle is not rebuilt here)
- Creates and publishes a platform sub-package (@chelonia/cli-<arch>-<os>) for each target
- Reconciles optionalDependencies as a final safety check
After the sub-packages are published, npm publish proceeds to publish the main @chelonia/cli package, whose optionalDependencies now point to the freshly published sub-packages.
Generate the release tarballs (for the GitHub release):
```
deno task dist
git diff --exit-code -- build   # fails if the rebuild diverged from the tag
```
This lints, builds, and compiles native binaries into dist/chel-v<version>-<target>.tar.gz, printing SHA256 checksums. It must run after npm publish: deno task dist rebuilds build/, which might dirty the working tree that the publish verification requires to be clean. The git diff --exit-code -- build afterwards confirms the rebuild is byte-identical to the version commit, i.e. that the build is reproducible.
Push the version commit and tag:
```
git push && git push --tags
```

History

See HISTORY.md

License

AGPL-3.0

Name		Name	Last commit message	Last commit date
Latest commit History 135 Commits
.github		.github
.vscode		.vscode
bin		bin
build		build
scripts		scripts
src		src
test		test
vendor		vendor
.gitignore		.gitignore
.npmrc		.npmrc
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
HISTORY.md		HISTORY.md
LICENSE		LICENSE
README.md		README.md
deno.json		deno.json
deno.lock		deno.lock
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Repository files navigation

Chel: Chelonia Command-line Interface

All Available Commands

`chel pin` - Per-Contract Versioning System

`chel init` - Generate `chel.toml`

`chel serve` - Development Server with Contract Preloading

`chel keygen`

`chel serve`

`chel manifest`

`chel deploy`

`chel eventsAfter`

Decrypting events with `--keys`

`chel migrate`

Examples

Configuration Files

`chel.toml` — Runtime CLI Configuration

`chelonia.json` — App Properties

Supported Platforms

Packaging

History

License

About

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

Uh oh!

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Chel: Chelonia Command-line Interface

All Available Commands

chel pin - Per-Contract Versioning System

chel init - Generate chel.toml

chel serve - Development Server with Contract Preloading

chel keygen

chel serve

chel manifest

chel deploy

chel eventsAfter

Decrypting events with --keys

chel migrate

Examples

Configuration Files

chel.toml — Runtime CLI Configuration

chelonia.json — App Properties

Supported Platforms

Packaging

History

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

`chel pin` - Per-Contract Versioning System

`chel init` - Generate `chel.toml`

`chel serve` - Development Server with Contract Preloading

`chel keygen`

`chel serve`

`chel manifest`

`chel deploy`

`chel eventsAfter`

Decrypting events with `--keys`

`chel migrate`

`chel.toml` — Runtime CLI Configuration

`chelonia.json` — App Properties