Provisioning from the Shell

The chapter advances the argument that provisioning a complete system from the command line means understanding the client that runs the commands, then each provisioning command in the order it must be run, then the smaller commands they are built from, and finally how to tie them together into a repeatable script — and it proceeds in that order. It begins by establishing the client and the rules it enforces in The shell and provisioning, which explains how the shell speaks to the backend and why provisioning follows a fixed sequence; this is the premise the rest of the chapter builds on. From there it walks the sequence one stage at a time — Provisioning the system, then Provisioning a tenant, then Provisioning a party — each command standing in for the wizard it replaces. It then opens up the machinery in The supporting commands, the smaller commands the provision phases call and that you can run by hand to inspect the system or recover a failed run, before showing in Scripts how the shell runs those commands unattended from a file. Finally A complete example runs the fast Acme Corporation path from a single shipped script, and A custom example: your own organisation points to the equivalent script for building your own house instead, before the Conclusion draws these steps together.

ores.shell is ORE Studio's interactive command-line client. Like the desktop application it speaks to the backend services over the message bus, so anything it does respects the same validation, audit trail, and permissions. Start it, connect, and type help to see the available commands; every command described here also explains its own arguments through the shell's built-in help.

Provisioning from the shell follows exactly the sequence described in the previous chapter — system, then tenant, then party — including the logouts and logins between the stages, because each login is what refreshes your session's view of the system's state. The difference is that each wizard collapses into a single command whose options carry the same defaults the wizard pre-fills, so the common case needs very few of them.

provision system performs the System Provisioner's work: it checks the installation is in bootstrap mode, creates the platform administrator, logs in as that account, and provisions the first tenant together with its tenant administrator.

provision system super_admin Secure-Password-123 admin@localhost.com --tenant-admin-password Secure-Password-123 --tenant-hostname default
logout
exit

The tenant administrator's password is the only option without a default — everything else mirrors the wizard's single-tenant mode: tenant code default, name Default Tenant, type evaluation, and the tenant administrator named tenant_admin with the e-mail address admin@<code>.com. To provision a custom tenant instead — what the wizard calls multi-tenant mode — override what you need with --tenant-code, --tenant-name, --tenant-type, --tenant-hostname, --tenant-description, --tenant-admin and --tenant-admin-email.

The command validates everything before touching the backend, refuses to run when you are already logged in or the system is not in bootstrap mode, and on success prints the login for the next stage:

./projects/ores.compass/compass.sh shell << 'EOF'
<<shellprov-system>>
EOF

✓ Connected to nats://localhost:42222
⚠ WARNING: System is in BOOTSTRAP MODE
ores-shell> [1/3] Creating initial admin account 'super_admin'...
  Account created (ID: b88d04ec-ac25-4137-981a-ddefb1d92592).
[2/3] Logging in as 'super_admin'...
✓ Login successful!
[3/3] Provisioning tenant 'default'...
✓ System provisioned. Tenant 'Default Tenant' (ID: 93b5d425-...), admin 'tenant_admin'.
Next: logout, then: login tenant_admin@default <password>  — the tenant is in bootstrap mode; run provision tenant.
ores-shell> ✓ Logged out successfully.
ores-shell> Bye!

Note the login principal is the username at the tenant's hostname (tenant_admin@default above), not its display name.

provision tenant performs the Tenant Provisioner's work for the tenant you are logged in to. Log in as the tenant administrator the previous stage created — the tenant is in bootstrap mode, which is exactly what the command requires — and run:

login tenant_admin@default Secure-Password-123
provision tenant --source synthetic --seed 42
logout
exit

./projects/ores.compass/compass.sh shell << 'EOF'
<<shellprov-tenant>>
EOF

ores-shell> ✓ Login successful!
ores-shell> Using bundle 'base' (first available).
[1/4] Publishing bundle 'base'...
  Dispatched 31 dataset(s); workflow instance: 7c059b7f-...
✓ All 31 step(s) completed.
[2/4] Generating synthetic organisation...
✓ Synthetic organisation generated (seed 42):
  parties:             5
  counterparties:      10
  ...
[3/4] Associating 'tenant_admin' with the operational parties...
  5 parties associated.
[4/4] Finalizing tenant provisioning...
✓ Tenant provisioned: bundle 'base', 5 parties associated.
ores-shell> ✓ Logged out successfully.
ores-shell> Bye!

With no options this publishes the first available reference data catalogue and uses the GLEIF registry as the data source, just as the wizard's defaults do. The options mirror the wizard's Welcome-page fork and its Manual sub-pages:

• --source acme — the fastest path to a fully populated, realistic installation, matching the wizard's Acme Corporation (full sample bank) choice. Ignores every other option below: it imports Acme Corporation's four-entity LEI hierarchy and publishes all of its business units, portfolios, books, and staff accounts server-side in one command. See the Acme Corporation chapter for what this produces, and A complete example below for the full worked run.
• --bundle <code> selects a specific reference-data catalogue for the Manual path (bundles list shows what is available).
• --source gleif (the default when --source is omitted) optionally takes --root-lei <lei> to build your own house hierarchy from a real organisation; find the LEI with lei countries and lei entities <country> --filter <text>.
• --source synthetic generates a realistic but fictional organisation instead, for evaluation or testing without importing real data. All the generation controls from the wizard's synthetic page are available as options with the same defaults (--party-count, --counterparty-count, --portfolio-leaf-count and so on); --seed <n> makes the result reproducible — the same seed always generates the same organisation, names included.

Choose --source acme to explore ORE Studio quickly; choose gleif or synthetic when you want to model your own organisation instead.

The command publishes the catalogue and waits while the backend works through its datasets, printing each step as it completes; generates the synthetic organisation when selected; associates your administrator account with every operational party; and finally marks the tenant active. As with the wizard, log out and back in afterwards so your session picks up the now-active tenant.

provision party performs the Party Provisioner's work for one party. Unlike the wizard — which runs for the party you selected at login — the command always names its target explicitly, either by its full name or by its identifier; parties list --category Operational shows the candidates:

login tenant_admin@default Secure-Password-123
provision party "Lloyds Wealth Management Ltd"
logout
exit

./projects/ores.compass/compass.sh shell << 'EOF'
<<shellprov-party>>
EOF

ores-shell> ✓ Login successful!
ores-shell> [1/5] Importing counterparties (dataset small)...
✓ All 1 step(s) completed.
[2/5] Publishing organisation structure and risk reporting...
✓ All 4 step(s) completed.
[3/5] Publishing synthetic market data configuration...
✓ All 2 step(s) completed.
[4/5] Publishing FX driver rates...
✓ All 1 step(s) completed.
[5/5] Activating party 'Lloyds Wealth Management Ltd'...
✓ Party 'Lloyds Wealth Management Ltd' provisioned and active.
ores-shell> ✓ Logged out successfully.
ores-shell> Bye!

The only option is --dataset-size small|large, selecting the counterparty import size (small is the default). The command imports the counterparties, then publishes every party-scoped bundle in turn – risk management (business units, portfolios, books, and report definitions; reports reference the book/portfolio tree, so both publish together), synthetic market data configuration (FX, IR curve, and any future asset class – adding one is a data change in dq_dataset_bundle_member_populate.sql, never a shell code change), and the curated FX driver-rate dataset – and finally activates the party.

The provision commands are built from smaller commands you can use on their own — to inspect the system, to recover when a step fails, or to assemble a custom flow. Each provision phase prints which of these it is performing, so a failed run tells you where to pick up by hand.

The provision commands call these in sequence; you can call them individually to inspect the system or to recover a failed run from where it stopped.

The shell runs scripts with the load command: one command per line, # starts a comment, and blank lines are ignored. A script stops at the first command that fails — so a run that reaches the end has genuinely succeeded — and reports the failing line and command. When you want a script to press on regardless, for example while exploring, pass --continue-on-error:

load my_script.ores
load my_script.ores --continue-on-error

ORE Studio ships a small library of provisioning scripts in projects/ores.shell/scripts/. Each .ores script in the library is generated from a documentation file alongside it that explains, step by step, what the script does and what it expects of the system — read that file before running a script for the first time. Treat the shipped scripts as templates: copy one and adjust the copy rather than editing the original, which the build regenerates.

The library's how_do_i_provision_the_system_with_acme_corporation_holding_group.ores provisions a complete system from a fresh installation with a single --source acme call: platform administrator, an Acme Corporation tenant, and all four of its legal entities — business units, portfolios, books, staff accounts, and market data — server-side orchestrated in one step. It is the quickest way to a fully populated installation and the recommended starting point for exploring ORE Studio; see the Acme Corporation chapter for what it produces. It expects a fresh installation in bootstrap mode, all services running, and a connected, logged-out session.

load projects/ores.shell/scripts/library/provisioning/how_do_i_provision_the_system_with_acme_corporation_holding_group.ores
exit

An error-free run ends with all four legal entities active (the excerpt below elides most of the per-entity dataset/bundle detail — the full output reports every step for all four companies as it lands):

./projects/ores.compass/compass.sh shell << 'EOF'
<<shellprov-acme>>
EOF

ores-shell> Loading script: .../how_do_i_provision_the_system_with_acme_corporation_holding_group.ores
> provision system super_admin Secure-Password-123 super_admin@localhost.com ...
✓ System provisioned. Tenant 'Acme Corporation' ...
> login tenant_admin@acme_corporation Secure-Password-123
✓ Login successful!
> provision tenant --source acme
Step 1: Publishing base reference data: ... completed
Step 2: Importing Acme Corporation LEI hierarchy: ... completed
Step 3: Publishing group-level staff: ... completed
Step 4: Publishing ACME Corporation UK plc: ... completed
Step 5: Publishing ACME Corporation US Inc: ... completed
Step 6: Publishing ACME Corporation HK Ltd: ... completed
Step 7: Granting cross-entity access: ... completed
✓ Acme Corporation holding group provisioned.
> logout
✓ Logged out successfully.
Script complete: 6 commands executed.

Unlike the generic provision party flow, --source acme handles every one of Acme's four legal entities internally — there is no per-party stage to call separately, and no seed to track: the same script against a fresh installation always produces the same four entities, the same fifty-eight staff, and the same structure.

Log in — from the shell or the desktop application — as tenant_admin@acme_corporation, select one of the four operating companies, and daily use begins, just as at the end of the previous chapter.

Where the Acme Corporation script above is the fast path, building your own house from scratch — modelling a real organisation, or a synthetic one shaped to your own testing needs — uses the generic three-stage sequence Provisioning the system through Provisioning a party set out earlier: provision system, then provision tenant --source gleif (or --source synthetic), then provision party for each party that needs its own counterparties and bundles. The library's barclays_system_provision.ores is the worked example of this path — real GLEIF-imported data rather than Acme's curated dataset — and follows exactly the same =load=/logout/login shape as the Acme example above, just with more stages since each party is provisioned individually.

The chapter set out to show that a complete system can be provisioned from the command line by understanding the client, the provisioning commands in sequence, the supporting commands beneath them, and the scripts that tie them together, and it has traced exactly that path. The shell speaks to the same backend services as the desktop application, so it enforces the same validation, audit trail, and permissions, and provisioning follows the same fixed sequence — system, then tenant, then party — with the logouts and logins between stages that refresh the session's view of the system. Each provision command collapses a wizard into a single line whose options carry the same defaults, and each is built from smaller supporting commands that can be run by hand to inspect the system or recover a failed run. The load command then runs those commands unattended from a file, and the shipped script library showed both paths executing end to end from a fresh installation: --source acme for the fast, fully populated Acme Corporation entity, and the generic gleif=/=synthetic sequence for building a house of your own. Because the same script against the same starting point always produces the same system, scripted provisioning is the natural tool for development environments, testing, and automation — everything the wizards do, reproducibly and without the desktop.