realms-gos 0.3.1

Realms Government Operating System - CLI and SDK for managing realms on the Internet Computer

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-gos, 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 deploy command 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-gos

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/Basilisk)
• 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 registry create

Create and optionally deploy a registry instance.

realms registry create [OPTIONS]

Options:
  --name TEXT              Registry name (optional)
  -o, --output-dir TEXT    Base output directory (default: .realms)
  -n, --network TEXT       Network to deploy to [local|staging|ic] (default: local)
  --deploy                 Deploy the registry after creation
  --identity TEXT          Identity PEM file or dfx identity name
  -m, --mode TEXT          Deploy mode: 'upgrade' or 'reinstall' (default: upgrade)

Examples:

# Create and deploy to local
realms registry create --deploy

# Create and deploy to staging (uses existing canister IDs from canister_ids.json)
realms registry create --deploy --network staging

# Create and deploy with reinstall (wipes stable memory)
realms registry create --deploy --network staging --mode reinstall

Note: For non-local networks (staging, ic), the CLI automatically copies registry canister IDs from the root canister_ids.json file, allowing deployment to existing canisters.

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

# Install pipx if you don't have it
pip install pipx

# Install realms-gos in an isolated environment
pipx install realms-gos

# 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-gos

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

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
• 🐛 Issue Tracker
• 💬 Discord Community