Chelonia Command-line Interface
npm install @chelonia/cliModern CLI for Chelonia contract development, deployment, and management.
```
chel
chel help [command]
chel version
chel pin [--dir
chel test
chel keygen [--out=
chel manifest [-k|--key
chel deploy
chel upload
chel serve [options]
chel latestState
chel eventsAfter [--limit N]
chel eventsBefore [--limit N]
chel hash
chel migrate --from
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.
šÆ Pin individual contracts to specific versions independently!
Key Features:
- ā
Per-contract versioning using chelonia.json configurationcontracts/
- ā
Individual contract pinning by specifying manifest file path
- ā
New directory structure:
- ā
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)chel pin
2. Pin from manifest: Use with the manifest file path
3. Contract files copied: Contract files (main/slim) and manifest are copied to new structure
Usage Examples:
`bashFirst, generate cryptographic keys (required for production)
chel keygen
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 serveServe Group Income app from extracted directory
chel serve ./gi-v2.0.0Serve 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.0Serve 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.jsRunning
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
``See HISTORY.md