This release is a pre-release and may not be stable for production use.
Realms CLI
Command-line tool for Realms GOS: build extensions and codices, run a realm locally, and deploy realms to the Internet Computer.
Installation
The package is realms-gos (the realms package on PyPI is unrelated).
Install it with pipx, which gives the CLI its own
environment; on Ubuntu 24.04 and Debian 12, plain pip install into the
system Python is refused ("externally-managed-environment").
sudo apt install pipx # or see pipx.pypa.io for other systems
pipx ensurepath # then open a new terminal
pipx install --pip-args=--pre realms-gos
realms --version
--pre is needed until 0.7.0 is final: the realms new extension|codex and
realms local commands below ship in the 0.7.0 release candidates.
No clone of the repository is needed.
Requirements: Python 3.8+ and Node.js 20+ with npm (extension frontends
are built with npm; realms local installs icp-cli through npm on first use).
Quick Start: an Extension and a Codex on a Local Realm
realms local start # local network + realm from the matching release
realms new extension my-hello-world # scaffold, npm install, build
realms new codex my-hello-codex --extension my_hello_world
realms local publish my-hello-world my-hello-codex # into the local file registry
realms local setup --codex my_hello_codex # install codex + extensions, launch
realms local call my_hello_world greet '{}' # "Hello, World!"
realms local status # realm URL and canister IDs
Open the realm URL, sign in with the local Internet Identity, join the realm,
and open My Hello World: its Say hello button shows Hello, World!.
After a change: bump version in the extension's manifest.json, run
npm run build in it, then realms local publish my-hello-world --install.
realms local add-admin <principal> makes a browser user an admin;
realms local stop stops the network.
Deploying Realms (dfx)
The realms realm … and realms registry … commands below deploy with
dfx
and need it installed (dfx --version).
Commands
realms realm create
Create (and optionally deploy) a new realm.
realms realm create [OPTIONS]
Common options:
--realm-name TEXT Realm name
--random Populate with random demo data
--citizens INTEGER Number of citizens to generate
--organizations INTEGER Number of organizations to generate
--transactions INTEGER Number of transactions to generate
--seed INTEGER Deterministic seed for random data
-n, --network TEXT Target network [local|staging|ic]
--deploy Deploy after creation
-m, --mode TEXT Deploy mode: 'auto', 'upgrade' or 'reinstall'
realms realm deploy
Deploy a previously-created realm folder.
realms realm deploy [OPTIONS]
Options:
--folder TEXT Path to generated realm folder
-n, --network TEXT Target network (default: local)
--clean Clean deployment (restart dfx)
--identity TEXT Identity PEM file or dfx identity name
-m, --mode TEXT Deploy mode: 'auto', 'upgrade' or 'reinstall'
--plain-logs Show full verbose output instead of progress UI
Examples:
# Basic deployment (auto-detects single realm folder under .realms/)
realms realm deploy
# Deploy to IC mainnet with a specific identity
realms realm deploy --network ic --identity ~/.config/dfx/identity/production/identity.pem
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
Configuration
Each generated realm folder contains a manifest.json describing the realm:
{
"type": "realm",
"name": "My Custom Realm",
"options": {
"random": {
"members": 100,
"organizations": 10,
"transactions": 200,
"disputes": 15,
"seed": 42
}
}
}
For the fleet itself (marketplace, file registry, token, NFT, demo realm) see
casals.json and docs/OPERATIONS.md; realm manifests live under examples/demo/.
Configuration Schema
- type: Always
realmfor a single-realm manifest - name: Display name for the realm
- options.random: Optional knobs for generated demo data
Development Setup
For contributing to the CLI tool:
git clone https://github.com/smart-social-contracts/realms-gos
cd realms-gos/cli
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
Running Tests
pytest
Code Formatting
black realms/
isort realms/
Examples
Government Services Platform
realms realm create \
--realm-name "Digital Government Services" \
--random --citizens 50 --organizations 5 --deploy
Multi-Realm (Mundus) Deployment
# Create a multi-realm ecosystem with a shared registry
realms mundus create --deploy
# Or use a custom manifest
realms mundus create --manifest examples/demo/manifest.json --deploy
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
- Show available commands:
realms --help - Show subcommand help:
realms realm --help,realms mundus --help, etc. - Check project status:
realms status
Provisioning is not a CLI command
The Realms product orchestra (marketplace, fleet file registry, token, NFT,
demo realm) is declared in the repo-root casals.json and deployed with
casals up from the Casals repo — see docs/OPERATIONS.md. The realms CLI
operates realms that exist; it does not mint or destroy canisters.
GUI alternative: the Package Manager extension
Most extension and codex management actions exposed by this CLI
(realms extension registry-install, realms extension runtime-install,
realms extension runtime-uninstall, realms codex install, ...) are
also available to realm administrators directly from the realm's
frontend, via the package_manager extension.
The extension provides three tabs (Installed / Browse / Upload) wired
to the same install_extension* / install_codex* /
uninstall_extension / uninstall_codex backend endpoints used by this
CLI. Once a realm has the package_manager extension installed, an admin
no longer needs CLI access to the host machine to add or remove
packages — they can do everything through the browser.
See docs/reference/EXTENSION_ARCHITECTURE.md → Package Manager Extension
for the full feature list, permissions model and caveats.
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-gos 0.8.0rc3
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_gos-0.8.0rc3.tar.gz | 8.2 MB | Without provenance | Details for realms_gos-0.8.0rc3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| realms_gos-0.8.0rc3-py3-none-any.whl | Python 3 | none | any | Details for realms_gos-0.8.0rc3-py3-none-any.whl |
Total release size: 16.7 MB
Release files / realms_gos-0.8.0rc3.tar.gz
| Download URL | realms_gos-0.8.0rc3.tar.gz |
|---|---|
| Size | 8.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d7bc85d32bd56ed6ff10401146b7ce2dc0e2b866f1db9b7dc2f5fcf308aa430a
|
|
BLAKE2b-256 checksum How to use checksums |
13920f0a7604b3a06fcde833dad2f24320c6f0e08ddf0a6817b94d998f625972
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.22
|
Release files / realms_gos-0.8.0rc3-py3-none-any.whl
| Download URL | realms_gos-0.8.0rc3-py3-none-any.whl |
|---|---|
| Size | 8.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2e1f1e73a3cd5d09259793060f1d40f0d86487572e61cd03a699f19f57c73467
|
|
BLAKE2b-256 checksum How to use checksums |
58c9352f6819a297604074f44bf60628918fb3e4c310339ee580fad5718c788a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.22
|
Security for realms-gos 0.8.0rc3
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.