# 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)
```bash
sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
```
- **Required for**: Canister deployment, local replica management
- **Used by**: `realms deploy` command for backend/frontend deployment
- **Verify installation**: `dfx --version`
### 2. Node.js (v16 or later)
```bash
# 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
```bash
pip install realms-cli
```
### From Source
```bash
git clone https://github.com/smartsocialcontracts/realms
cd realms/cli
pip install -e .
```
## Prerequisites
- Python 3.8+
- [dfx](https://internetcomputer.org/docs/current/developer-docs/setup/install/) (Internet Computer SDK)
- Node.js 16+
- Git
## Quick Start
### 1. Initialize a New Realm
```bash
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
```bash
cd my_gov_realm
realms deploy --file realm_config.json
```
Your realm will be available at `http://localhost:8000`
## Commands
### `realms init`
Initialize a new Realms project with scaffolding.
```bash
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:**
```bash
realms init --name "City Services" --id city_services --admin "2vxsx-fae"
```
### `realms deploy`
Deploy a Realms project based on configuration.
```bash
realms 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:**
```bash
# Basic deployment
realms deploy
# Deploy to IC mainnet
realms deploy --network ic --identity ~/.config/dfx/identity/production/identity.pem
# Deploy only specific extension phases
realms deploy --phases q1,q2
# Dry run to see what would be deployed
realms deploy --dry-run
```
### `realms status`
Show the current status of your Realms project.
```bash
realms status
```
### `realms validate`
Validate a realm configuration file.
```bash
realms validate [--file realm_config.json]
```
## Configuration
Realms projects are configured via `realm_config.json`:
```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 first
- `q1`, `q2`, `q3`, `q4`: Quarterly rollout phases
- `phase_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:
```bash
# 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 create --citizens 50
```
### Alternative: Using pip with venv
If you prefer manual environment management:
```bash
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:
```bash
git clone https://github.com/smartsocialcontracts/realms
cd realms/cli
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
black realms_cli/
isort realms_cli/
```
## Examples
### Government Services Platform
```bash
realms init \
--name "Digital Government Services" \
--id gov_services \
--admin "rdmx6-jaaaa-aaaaa-aaadq-cai"
cd gov_services
realms deploy
```
### Multi-Phase Deployment
```json
{
"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:
```bash
realms deploy --phases initial
realms deploy --phases q1
realms deploy --phases q2
```
## Troubleshooting
### Common Issues
**dfx not found**
```bash
# Install dfx
sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
```
**Port already in use**
```bash
# Kill existing dfx processes
dfx stop
pkill dfx
```
**Extension deployment fails**
```bash
# 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 deploy --dry-run`
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Support
- 📖 [Documentation](https://docs.realms.dev)
- 🐛 [Issue Tracker](https://github.com/smartsocialcontracts/realms/issues)
- 💬 [Discord Community](https://discord.gg/realms)
Raw data
{
"_id": null,
"home_page": null,
"name": "realms-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "realms, cli, internet-computer, dfx, blockchain",
"author": null,
"author_email": "Realms Team <team@realms.dev>",
"download_url": "https://files.pythonhosted.org/packages/46/7d/e2ec597b44d781824d70eb4b09f2db89219416a01f94583694bde73799b7/realms_cli-0.1.2.tar.gz",
"platform": null,
"description": "# Realms CLI\n\nA powerful command-line tool for managing Realms project lifecycle on the Internet Computer.\n\n## Features\n\n- **\ud83c\udfd7\ufe0f Project Scaffolding**: Initialize complete Realms projects with proper structure\n- **\ud83d\ude80 Automated Deployment**: Deploy backend + frontend + extensions with single command\n- **\ud83d\udce6 Extension Management**: Phased rollouts (q1-q4) with dependency management\n- **\u2699\ufe0f Post-Deployment Actions**: Automated setup and data population\n- **\ud83d\udd27 Configuration Validation**: Schema validation with helpful error messages\n- **\ud83d\udcca Project Status**: Check project health and deployment status\n\n## Prerequisites\n\nBefore installing realms-cli, ensure you have the following dependencies:\n\n### 1. DFX (DFINITY Canister SDK)\n```bash\nsh -ci \"$(curl -fsSL https://internetcomputer.org/install.sh)\"\n```\n- **Required for**: Canister deployment, local replica management\n- **Used by**: `realms deploy` command for backend/frontend deployment\n- **Verify installation**: `dfx --version`\n\n### 2. Node.js (v16 or later)\n```bash\n# Option 1: Download from https://nodejs.org\n# Option 2: Via package manager (Ubuntu/Debian)\ncurl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -\nsudo apt-get install -y nodejs\n\n# Option 3: Via nvm (recommended)\ncurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash\nnvm install 18\nnvm use 18\n```\n- **Required for**: Frontend building, npm package management\n- **Used by**: Frontend canister builds during deployment\n- **Verify installation**: `node --version && npm --version`\n\n## Installation\n\n```bash\npip install realms-cli\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/smartsocialcontracts/realms\ncd realms/cli\npip install -e .\n```\n\n## Prerequisites\n\n- Python 3.8+\n- [dfx](https://internetcomputer.org/docs/current/developer-docs/setup/install/) (Internet Computer SDK)\n- Node.js 16+\n- Git\n\n## Quick Start\n\n### 1. Initialize a New Realm\n\n```bash\nrealms init --name \"My Government Realm\" --id my_gov_realm\n```\n\nThis creates a complete project structure with:\n- Backend canister (Python/Kybra)\n- Frontend canister (SvelteKit)\n- Extension system\n- Configuration files\n- Deployment scripts\n\n### 2. Deploy Your Realm\n\n```bash\ncd my_gov_realm\nrealms deploy --file realm_config.json\n```\n\nYour realm will be available at `http://localhost:8000`\n\n## Commands\n\n### `realms init`\n\nInitialize a new Realms project with scaffolding.\n\n```bash\nrealms init [OPTIONS]\n\nOptions:\n -n, --name TEXT Realm name\n --id TEXT Realm ID (lowercase, underscores)\n --admin TEXT Admin principal ID\n --network TEXT Target network [local|staging|ic]\n --interactive/--no-interactive Interactive mode (default: true)\n -o, --output TEXT Output directory (default: current)\n```\n\n**Example:**\n```bash\nrealms init --name \"City Services\" --id city_services --admin \"2vxsx-fae\"\n```\n\n### `realms deploy`\n\nDeploy a Realms project based on configuration.\n\n```bash\nrealms deploy [OPTIONS]\n\nOptions:\n -f, --file TEXT Configuration file (default: realm_config.json)\n -n, --network TEXT Override network from config\n --skip-extensions Skip extension deployment\n --skip-post-deployment Skip post-deployment actions\n --phases TEXT Deploy specific phases only\n --dry-run Show deployment plan without executing\n --identity TEXT Identity file for authentication\n```\n\n**Examples:**\n```bash\n# Basic deployment\nrealms deploy\n\n# Deploy to IC mainnet\nrealms deploy --network ic --identity ~/.config/dfx/identity/production/identity.pem\n\n# Deploy only specific extension phases\nrealms deploy --phases q1,q2\n\n# Dry run to see what would be deployed\nrealms deploy --dry-run\n```\n\n### `realms status`\n\nShow the current status of your Realms project.\n\n```bash\nrealms status\n```\n\n### `realms validate`\n\nValidate a realm configuration file.\n\n```bash\nrealms validate [--file realm_config.json]\n```\n\n## Configuration\n\nRealms projects are configured via `realm_config.json`:\n\n```json\n{\n \"realm\": {\n \"id\": \"my_government_realm\",\n \"name\": \"My Government Realm\",\n \"description\": \"A digital government platform\",\n \"admin_principal\": \"2vxsx-fae\",\n \"version\": \"1.0.0\"\n },\n \"deployment\": {\n \"network\": \"local\",\n \"clean_deploy\": true\n },\n \"extensions\": {\n \"initial\": [\n {\"name\": \"public_dashboard\", \"enabled\": true},\n {\"name\": \"citizen_dashboard\", \"enabled\": true}\n ],\n \"q1\": [\n {\"name\": \"vault\", \"enabled\": true}\n ]\n },\n \"post_deployment\": {\n \"actions\": [\n {\n \"type\": \"extension_call\",\n \"name\": \"Load demo data\",\n \"extension_name\": \"demo_loader\",\n \"function_name\": \"load\",\n \"args\": {\"step\": \"base_setup\"}\n }\n ]\n }\n}\n```\n\n### Configuration Schema\n\n- **realm**: Basic realm metadata (id, name, admin, etc.)\n- **deployment**: Deployment settings (network, port, identity)\n- **extensions**: Extensions organized by deployment phases\n- **post_deployment**: Actions to run after deployment\n\n## Extension Phases\n\nExtensions can be organized into deployment phases:\n\n- `initial`: Core extensions deployed first\n- `q1`, `q2`, `q3`, `q4`: Quarterly rollout phases\n- `phase_1`, `phase_2`, etc.: Custom phases\n\n## Post-Deployment Actions\n\nAutomate setup tasks after deployment:\n\n- **extension_call**: Call extension functions\n- **script**: Run shell scripts\n- **wait**: Add delays between actions\n\n## Installation\n\n### Recommended: Using pipx (Isolated Environment)\n\nThe easiest way to install the Realms CLI is using `pipx`, which automatically manages isolated Python environments:\n\n```bash\n# Install pipx if you don't have it\npip install pipx\n\n# Install realms-cli in an isolated environment\npipx install realms-cli\n\n# Use the CLI tool (no venv activation needed)\nrealms --help\nrealms create --citizens 50\n```\n\n### Alternative: Using pip with venv\n\nIf you prefer manual environment management:\n\n```bash\npython -m venv realms-env\nsource realms-env/bin/activate # On Windows: realms-env\\Scripts\\activate\npip install realms-cli\n```\n\n### Development Setup\n\nFor contributing to the CLI tool:\n\n```bash\ngit clone https://github.com/smartsocialcontracts/realms\ncd realms/cli\npython -m venv venv\nsource venv/bin/activate\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Formatting\n\n```bash\nblack realms_cli/\nisort realms_cli/\n```\n\n## Examples\n\n### Government Services Platform\n\n```bash\nrealms init \\\n --name \"Digital Government Services\" \\\n --id gov_services \\\n --admin \"rdmx6-jaaaa-aaaaa-aaadq-cai\"\n\ncd gov_services\nrealms deploy\n```\n\n### Multi-Phase Deployment\n\n```json\n{\n \"extensions\": {\n \"initial\": [\n {\"name\": \"public_dashboard\", \"enabled\": true}\n ],\n \"q1\": [\n {\"name\": \"citizen_dashboard\", \"enabled\": true},\n {\"name\": \"notifications\", \"enabled\": true}\n ],\n \"q2\": [\n {\"name\": \"land_registry\", \"enabled\": true},\n {\"name\": \"justice_litigation\", \"enabled\": true}\n ]\n }\n}\n```\n\nDeploy phases incrementally:\n```bash\nrealms deploy --phases initial\nrealms deploy --phases q1\nrealms deploy --phases q2\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**dfx not found**\n```bash\n# Install dfx\nsh -ci \"$(curl -fsSL https://internetcomputer.org/install.sh)\"\n```\n\n**Port already in use**\n```bash\n# Kill existing dfx processes\ndfx stop\npkill dfx\n```\n\n**Extension deployment fails**\n```bash\n# Check extension directory exists\nls extensions/\n# Reinstall extensions\n./scripts/install_extensions.sh\n```\n\n### Getting Help\n\n- Check project status: `realms status`\n- Validate configuration: `realms validate`\n- Use dry-run mode: `realms deploy --dry-run`\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://docs.realms.dev)\n- \ud83d\udc1b [Issue Tracker](https://github.com/smartsocialcontracts/realms/issues)\n- \ud83d\udcac [Discord Community](https://discord.gg/realms)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI tool for managing Realms project lifecycle",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/smartsocialcontracts/realms/issues",
"Documentation": "https://docs.realms.dev",
"Homepage": "https://github.com/smartsocialcontracts/realms",
"Repository": "https://github.com/smartsocialcontracts/realms"
},
"split_keywords": [
"realms",
" cli",
" internet-computer",
" dfx",
" blockchain"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "696d8c1c1b5bc5043be52da5285614ed16657ca6264bea4b2a4fac445cb8217d",
"md5": "6ce8c82b91233343720463e8204726bd",
"sha256": "3fe00f39023c73de54a4cfb155b8a13220761a4dbecf72bd0f21640262b1cb98"
},
"downloads": -1,
"filename": "realms_cli-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6ce8c82b91233343720463e8204726bd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 57731,
"upload_time": "2025-11-01T20:55:41",
"upload_time_iso_8601": "2025-11-01T20:55:41.342284Z",
"url": "https://files.pythonhosted.org/packages/69/6d/8c1c1b5bc5043be52da5285614ed16657ca6264bea4b2a4fac445cb8217d/realms_cli-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "467de2ec597b44d781824d70eb4b09f2db89219416a01f94583694bde73799b7",
"md5": "ec4a7a7d8b49543afebb1c187868455d",
"sha256": "b4480afebb56f442b5ff3a52e172809d66288ea9225834bc76ccad72ce3c0f92"
},
"downloads": -1,
"filename": "realms_cli-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "ec4a7a7d8b49543afebb1c187868455d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 56029,
"upload_time": "2025-11-01T20:55:42",
"upload_time_iso_8601": "2025-11-01T20:55:42.293955Z",
"url": "https://files.pythonhosted.org/packages/46/7d/e2ec597b44d781824d70eb4b09f2db89219416a01f94583694bde73799b7/realms_cli-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 20:55:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "smartsocialcontracts",
"github_project": "realms",
"github_not_found": true,
"lcname": "realms-cli"
}
JSON
