Realms CLI
A powerful command-line tool for managing Realms project lifecycle on the Internet Computer.
Features
- 🏗️ Project Scaffolding: Initialize complete Realms projects with proper structure
- 🚀 Automated Deployment: Deploy backend + frontend + extensions with single command
- 📦 Extension Management: Phased rollouts (q1-q4) with dependency management
- ⚙️ Post-Deployment Actions: Automated setup and data population
- 🔧 Configuration Validation: Schema validation with helpful error messages
- 📊 Project Status: Check project health and deployment status
Prerequisites
Before installing realms-cli, ensure you have the following dependencies:
1. DFX (DFINITY Canister SDK)
sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
- Required for: Canister deployment, local replica management
- Used by:
realms realm deploycommand for backend/frontend deployment - Verify installation:
dfx --version
2. Node.js (v16 or later)
# Option 1: Download from https://nodejs.org
# Option 2: Via package manager (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# Option 3: Via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
- Required for: Frontend building, npm package management
- Used by: Frontend canister builds during deployment
- Verify installation:
node --version && npm --version
Installation
pip install realms-cli
From Source
git clone https://github.com/smartsocialcontracts/realms
cd realms/cli
pip install -e .
Prerequisites
- Python 3.8+
- dfx (Internet Computer SDK)
- Node.js 16+
- Git
Quick Start
1. Initialize a New Realm
realms init --name "My Government Realm" --id my_gov_realm
This creates a complete project structure with:
- Backend canister (Python/Kybra)
- Frontend canister (SvelteKit)
- Extension system
- Configuration files
- Deployment scripts
2. Deploy Your Realm
cd my_gov_realm
realms realm deploy --file realm_config.json
Your realm will be available at http://localhost:8000
Commands
realms init
Initialize a new Realms project with scaffolding.
realms init [OPTIONS]
Options:
-n, --name TEXT Realm name
--id TEXT Realm ID (lowercase, underscores)
--admin TEXT Admin principal ID
--network TEXT Target network [local|staging|ic]
--interactive/--no-interactive Interactive mode (default: true)
-o, --output TEXT Output directory (default: current)
Example:
realms init --name "City Services" --id city_services --admin "2vxsx-fae"
realms realm deploy
Deploy a Realms project based on configuration.
realms realm deploy [OPTIONS]
Options:
-f, --file TEXT Configuration file (default: realm_config.json)
-n, --network TEXT Override network from config
--skip-extensions Skip extension deployment
--skip-post-deployment Skip post-deployment actions
--phases TEXT Deploy specific phases only
--dry-run Show deployment plan without executing
--identity TEXT Identity file for authentication
Examples:
# Basic deployment
realms realm deploy
# Deploy to IC mainnet
realms realm deploy --network ic --identity ~/.config/dfx/identity/production/identity.pem
# Deploy only specific extension phases
realms realm deploy --phases q1,q2
# Dry run to see what would be deployed
realms realm deploy --dry-run
realms status
Show the current status of your Realms project.
realms status
realms validate
Validate a realm configuration file.
realms validate [--file realm_config.json]
Configuration
Realms projects are configured via realm_config.json:
{
"realm": {
"id": "my_government_realm",
"name": "My Government Realm",
"description": "A digital government platform",
"admin_principal": "2vxsx-fae",
"version": "1.0.0"
},
"deployment": {
"network": "local",
"clean_deploy": true
},
"extensions": {
"initial": [
{"name": "public_dashboard", "enabled": true},
{"name": "citizen_dashboard", "enabled": true}
],
"q1": [
{"name": "vault", "enabled": true}
]
},
"post_deployment": {
"actions": [
{
"type": "extension_call",
"name": "Load demo data",
"extension_name": "demo_loader",
"function_name": "load",
"args": {"step": "base_setup"}
}
]
}
}
Configuration Schema
- realm: Basic realm metadata (id, name, admin, etc.)
- deployment: Deployment settings (network, port, identity)
- extensions: Extensions organized by deployment phases
- post_deployment: Actions to run after deployment
Extension Phases
Extensions can be organized into deployment phases:
initial: Core extensions deployed firstq1,q2,q3,q4: Quarterly rollout phasesphase_1,phase_2, etc.: Custom phases
Post-Deployment Actions
Automate setup tasks after deployment:
- extension_call: Call extension functions
- script: Run shell scripts
- wait: Add delays between actions
Installation
Recommended: Using pipx (Isolated Environment)
The easiest way to install the Realms CLI is using pipx, which automatically manages isolated Python environments:
# Install pipx if you don't have it
pip install pipx
# Install realms-cli in an isolated environment
pipx install realms-cli
# Use the CLI tool (no venv activation needed)
realms --help
realms realm create --citizens 50
Alternative: Using pip with venv
If you prefer manual environment management:
python -m venv realms-env
source realms-env/bin/activate # On Windows: realms-env\Scripts\activate
pip install realms-cli
Development Setup
For contributing to the CLI tool:
git clone https://github.com/smartsocialcontracts/realms
cd realms/cli
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
Running Tests
pytest
Code Formatting
black realms_cli/
isort realms_cli/
Examples
Government Services Platform
realms init \
--name "Digital Government Services" \
--id gov_services \
--admin "rdmx6-jaaaa-aaaaa-aaadq-cai"
cd gov_services
realms realm deploy
Multi-Phase Deployment
{
"extensions": {
"initial": [
{"name": "public_dashboard", "enabled": true}
],
"q1": [
{"name": "citizen_dashboard", "enabled": true},
{"name": "notifications", "enabled": true}
],
"q2": [
{"name": "land_registry", "enabled": true},
{"name": "justice_litigation", "enabled": true}
]
}
}
Deploy phases incrementally:
realms realm deploy --phases initial
realms realm deploy --phases q1
realms realm deploy --phases q2
Troubleshooting
Common Issues
dfx not found
# Install dfx
sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
Port already in use
# Kill existing dfx processes
dfx stop
pkill dfx
Extension deployment fails
# Check extension directory exists
ls extensions/
# Reinstall extensions
./scripts/install_extensions.sh
Getting Help
- Check project status:
realms status - Validate configuration:
realms validate - Use dry-run mode:
realms realm deploy --dry-run
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
License
MIT License - see LICENSE file for details.
Support
Metadata
Release files for realms-cli 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| realms_cli-0.2.0.tar.gz | 85.5 kB | Without provenance | Details for realms_cli-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| realms_cli-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for realms_cli-0.2.0-py3-none-any.whl |
Total release size: 172.1 kB
Release files / realms_cli-0.2.0.tar.gz
| Download URL | realms_cli-0.2.0.tar.gz |
|---|---|
| Size | 85.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
94152d89b3495b2312afe0b4efe3733b3285ea758550fc6f3e996a9d7d1dee63
|
|
BLAKE2b-256 checksum How to use checksums |
6bb5a8b4c042195966e7e91f66476ca36987584ca8a3f817393c8b9a2d8f785d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.19
|
Release files / realms_cli-0.2.0-py3-none-any.whl
| Download URL | realms_cli-0.2.0-py3-none-any.whl |
|---|---|
| Size | 86.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c5911c341c5c1f45aeee5406acfdbab9dffe4f3d488529b3485229335485bcb6
|
|
BLAKE2b-256 checksum How to use checksums |
0a48c79ed7ebd5c067790c90374fa37b0aee692b08fd4e71f15a75049ed94e43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.19
|
Security for realms-cli 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.