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 ] [--overwrite]
chel test
chel keygen [--out=]
chel manifest [-k|--key [-k|--key ...]] [--out=] [-s|--slim ] [-v|--version ]
chel deploy [ [ ...]]
chel upload [ [ ...]]
chel serve [options]
chel latestState
chel eventsAfter [--limit N]
chel eventsBefore [--limit N]
chel hash
chel migrate --from --to --out
`

Note: in many (if not all) instances, the 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.

$3

🎯 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///
- ✅ Manifest-based workflow - requires existing manifest files
- ✅ Ecosystem-agnostic - no coupling to Node.js/npm

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

Usage Examples:
`bash


First, generate cryptographic keys (required for production)

chel keygen

Then pin contracts with re-signing

chel pin

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):
`json
{
"contracts": {
"chatroom": {
"version": "2.0.6",
"path": "contracts/gi.contracts_chatroom/2.0.6/chatroom.2.0.6.manifest.json"
},
"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

$3

`
chel serve [options]

OPTIONS

--dashboard-port set dashboard port (default: 8888)
--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/// directories into the database on startup in development mode.

Example Output:
`bash
$ 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:
`bash


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:
1. Contract Discovery - Scans contracts/// directories
2. Manifest Collection - Finds all .manifest.json files
3. Database Preloading - Deploys all contracts with content-addressed storage
4. Server Startup - Starts dashboard and application servers
5. Ready for Development - All historical contracts available for message processing

$3

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

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

$3

Starts a local development server for Chelonia applications.

`
chel serve [options]

OPTIONS

--dashboard-port set dashboard port (default: 8888)
--port set application port (default: 8000)
`

Example:
`bash


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)

$3

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": " by default",
"contract": { "hash": "", "file": "contract-bundle.js" },
"contractSlim": { "hash": "", "file": "contract-slim.js" },
"authors": [
{"cipher": "algo", "key": ""},
{"cipher": "algo", "key": ""}
]
}),
"signature": {
"key": "",
"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.

$3

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

History

See HISTORY.md

License

AGPL-3.0