dohertj2/ScadaBridge
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(m4.3): reconcile CLI README + Component-CLI to registered commands/options (document bundle group; fix option drift)

Browse Source
This commit is contained in:
Joseph Doherty
2026-06-16 20:30:40 -04:00
parent 0780c2e49e
commit dd545281e6
2 changed files with 313 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/requirements/Component-CLI.md
+36 -21
View File
@@ -62,17 +62,17 @@ scadabridge template create --name <name> [--description <desc>] [--parent-id <i
scadabridge template update --id <id> [--name <name>] [--description <desc>] [--parent-id <id>] scadabridge template update --id <id> [--name <name>] [--description <desc>] [--parent-id <id>]
scadabridge template validate --id <id> scadabridge template validate --id <id>
scadabridge template delete --id <id> scadabridge template delete --id <id>
scadabridge template attribute add --template-id <id> --name <name> --data-type <type> [--value <value>] [--description <desc>] [--data-source <ref>] [--locked <bool>] scadabridge template attribute add --template-id <id> --name <name> --data-type <type> [--value <value>] [--description <desc>] [--data-source <ref>] [--locked]
scadabridge template attribute update --id <id> [--name <name>] [--data-type <type>] [--value <value>] [--description <desc>] [--data-source <ref>] [--locked <bool>] scadabridge template attribute update --id <id> [--name <name>] [--data-type <type>] [--value <value>] [--description <desc>] [--data-source <ref>] [--locked]
scadabridge template attribute delete --id <id> scadabridge template attribute delete --id <id>
scadabridge template alarm add --template-id <id> --name <name> --trigger-type <type> --priority <n> [--description <desc>] [--trigger-config <json>] [--locked <bool>] scadabridge template alarm add --template-id <id> --name <name> --trigger-type <type> --priority <n> [--description <desc>] [--trigger-config <json>] [--locked]
scadabridge template alarm update --id <id> [--name <name>] [--trigger-type <type>] [--priority <n>] [--description <desc>] [--trigger-config <json>] [--locked <bool>] scadabridge template alarm update --id <id> --name <name> --trigger-type <type> --priority <n> [--description <desc>] [--trigger-config <json>] [--locked]
scadabridge template alarm delete --id <id> scadabridge template alarm delete --id <id>
scadabridge template script add --template-id <id> --name <name> --code <code> --trigger-type <type> [--trigger-config <json>] [--locked <bool>] [--parameters <json>] [--return-def <json>] scadabridge template script add --template-id <id> --name <name> --code <code> --trigger-type <type> [--trigger-config <json>] [--locked] [--parameters <json>] [--return-def <json>]
scadabridge template script update --id <id> [--name <name>] [--code <code>] [--trigger-type <type>] [--trigger-config <json>] [--locked <bool>] [--parameters <json>] [--return-def <json>] scadabridge template script update --id <id> --name <name> --code <code> --trigger-type <type> [--trigger-config <json>] [--locked] [--parameters <json>] [--return-def <json>]
scadabridge template script delete --id <id> scadabridge template script delete --id <id>
scadabridge template composition add --template-id <id> --instance-name <name> --composed-template-id <id> scadabridge template composition add --template-id <id> --instance-name <name> --composed-template-id <id>
scadabridge template composition delete --template-id <id> --instance-name <name> scadabridge template composition delete --id <id>
scadabridge template native-alarm-source add --template-id <id> --name <name> --connection <name> --source-ref <ref> [--filter <expr>] [--description <desc>] [--locked] scadabridge template native-alarm-source add --template-id <id> --name <name> --connection <name> --source-ref <ref> [--filter <expr>] [--description <desc>] [--locked]
scadabridge template native-alarm-source list --template-id <id> scadabridge template native-alarm-source list --template-id <id>
scadabridge template native-alarm-source remove --id <id> scadabridge template native-alarm-source remove --id <id>
@@ -165,8 +165,8 @@ scadabridge deploy status [--instance-id <id>] [--status <status>] [--page <n>]
``` ```
scadabridge data-connection list [--site-id <id>] scadabridge data-connection list [--site-id <id>]
scadabridge data-connection get --id <id> scadabridge data-connection get --id <id>
scadabridge data-connection create --site-id <id> --name <name> --protocol <protocol> [--backup-config <json>] [--failover-retry-count <n>] scadabridge data-connection create --site-id <id> --name <name> --protocol <protocol> [--primary-config <json>] [--backup-config <json>] [--failover-retry-count <n>]
scadabridge data-connection update --id <id> [--name <name>] [--protocol <protocol>] [--backup-config <json>] [--failover-retry-count <n>] scadabridge data-connection update --id <id> --name <name> --protocol <protocol> [--primary-config <json>] [--backup-config <json>] [--failover-retry-count <n>]
scadabridge data-connection delete --id <id> scadabridge data-connection delete --id <id>
``` ```
@@ -192,32 +192,36 @@ scadabridge notification create --name <name> --emails <comma-separated>
scadabridge notification update --id <id> [--name <name>] [--emails <comma-separated>] scadabridge notification update --id <id> [--name <name>] [--emails <comma-separated>]
scadabridge notification delete --id <id> scadabridge notification delete --id <id>
scadabridge notification smtp list scadabridge notification smtp list
scadabridge notification smtp update --id <id> --server <host> --port <n> --auth-mode <mode> --from-address <email> scadabridge notification smtp update --id <id> --server <host> --port <n> --auth-mode <mode> --from-address <email> [--tls-mode <mode>] [--credentials <value>]
``` ```
### Security Commands ### Security Commands
``` ```
scadabridge security api-key list scadabridge security api-key list
scadabridge security api-key create --name <name> scadabridge security api-key create --name <name> --methods <comma-separated-method-names>
scadabridge security api-key update --id <id> --enabled <bool> scadabridge security api-key update --key-id <id> --enabled <bool>
scadabridge security api-key delete --id <id> scadabridge security api-key set-methods --key-id <id> --methods <comma-separated-method-names>
scadabridge security api-key delete --key-id <id>
scadabridge security role-mapping list scadabridge security role-mapping list
scadabridge security role-mapping create --ldap-group <group> --role <role> scadabridge security role-mapping create --ldap-group <group> --role <role>
scadabridge security role-mapping update --id <id> [--ldap-group <group>] [--role <role>] scadabridge security role-mapping update --id <id> [--ldap-group <group>] [--role <role>]
scadabridge security role-mapping delete --id <id> scadabridge security role-mapping delete --id <id>
scadabridge security scope-rule list [--mapping-id <id>] scadabridge security scope-rule list --mapping-id <id>
scadabridge security scope-rule add --mapping-id <id> --site-id <id> scadabridge security scope-rule add --mapping-id <id> --site-id <id>
scadabridge security scope-rule delete --id <id> scadabridge security scope-rule delete --id <id>
``` ```
### Audit Log Commands ### Configuration-Change Audit Commands
The `audit-config` group queries the configuration-change audit trail (the `IAuditService`
record of admin edits). `audit-log` is a deprecated alias that still works but emits a
warning; migrate scripts to `audit-config`.
``` ```
scadabridge audit-log query [--user <username>] [--entity-type <type>] [--action <action>] [--from <date>] [--to <date>] [--page <n>] [--page-size <n>] scadabridge audit-config query [--user <username>] [--entity-type <type>] [--action <action>] [--from <date>] [--to <date>] [--page <n>] [--page-size <n>]
``` ```
The legacy `audit-log query` above targets the original configuration-change audit The new centralized Audit Log component (#23) is exposed via the `scadabridge audit` group below.
(IAuditService) surface. The new centralized Audit Log component (#23) is exposed via
the `scadabridge audit` group below.
### Centralized Audit Commands ### Centralized Audit Commands
@@ -230,7 +234,7 @@ require the `OperationalAudit` permission; `audit export` additionally requires
exit code 2) on denial. exit code 2) on denial.
``` ```
scadabridge audit query --since <t> [--until <t>] [--channel <c>] [--kind <k>] [--status <s>] [--site <s>] [--instance <i>] [--target <t>] [--actor <a>] [--correlation-id <id>] [--errors-only] [--page <n>] [--page-size <n>] scadabridge audit query [--since <t>] [--until <t>] [--channel <c>] [--kind <k>] [--status <s>] [--site <s>] [--target <t>] [--actor <a>] [--correlation-id <id>] [--execution-id <id>] [--parent-execution-id <id>] [--errors-only] [--page-size <n>] [--all]
scadabridge audit export --since <t> --until <t> --format csv|jsonl|parquet --output <path> [--channel <c>] [--kind <k>] [--status <s>] [--site <s>] [--target <t>] [--actor <a>] scadabridge audit export --since <t> --until <t> --format csv|jsonl|parquet --output <path> [--channel <c>] [--kind <k>] [--status <s>] [--site <s>] [--target <t>] [--actor <a>]
scadabridge audit verify-chain --month <YYYY-MM> scadabridge audit verify-chain --month <YYYY-MM>
``` ```
@@ -298,10 +302,21 @@ scadabridge db-connection delete --id <id>
scadabridge api-method list scadabridge api-method list
scadabridge api-method get --id <id> scadabridge api-method get --id <id>
scadabridge api-method create --name <name> --script <code> [--timeout <seconds>] [--parameters <json>] [--return-def <json>] scadabridge api-method create --name <name> --script <code> [--timeout <seconds>] [--parameters <json>] [--return-def <json>]
scadabridge api-method update --id <id> [--script <code>] [--timeout <seconds>] [--parameters <json>] [--return-def <json>] scadabridge api-method update --id <id> --script <code> [--timeout <seconds>] [--parameters <json>] [--return-def <json>]
scadabridge api-method delete --id <id> scadabridge api-method delete --id <id>
``` ```
### Bundle Commands (Transport #24)
```
scadabridge bundle export --output <path> [--passphrase <phrase>] [--all] [--include-dependencies] [--templates <names>] [--shared-scripts <names>] [--external-systems <names>] [--db-connections <names>] [--notification-lists <names>] [--smtp-configs <names>] [--api-methods <names>] [--source-environment <env>]
scadabridge bundle preview --input <path> [--passphrase <phrase>]
scadabridge bundle import --input <path> [--passphrase <phrase>] [--on-conflict skip|overwrite|rename]
```
Inbound API keys are not transported between environments — re-create them on the destination via CLI or UI.
Bundle commands use a 5-minute timeout.
The `--format json|table` option is recursive and accepted on every command above. The `--format json|table` option is recursive and accepted on every command above.
## Configuration ## Configuration
src/ZB.MOM.WW.ScadaBridge.CLI/README.md
+277 -70
View File
@@ -226,48 +226,62 @@ scadabridge --url <url> template attribute delete --id <int>
Add an alarm definition to a template. Add an alarm definition to a template.
```sh ```sh
scadabridge --url <url> template alarm add --template-id <int> --name <string> --trigger-attribute <string> --condition <string> --setpoint <string> [--severity <string>] [--notification-list <string>] scadabridge --url <url> template alarm add --template-id <int> --name <string> --trigger-type <string> --priority <int> [--description <string>] [--trigger-config <json>] [--locked] [typed-setpoint-flags]
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--template-id` | yes | Template ID | | `--template-id` | yes | Template ID |
| `--name` | yes | Alarm name | | `--name` | yes | Alarm name |
| `--trigger-attribute` | yes | Attribute that triggers the alarm | | `--trigger-type` | yes | Trigger type (e.g. `ValueMatch`, `RangeViolation`, `RateOfChange`, `HiLo`, `Expression`) |
| `--condition` | yes | Trigger condition (e.g. `GreaterThan`, `LessThan`, `Equal`) | | `--priority` | yes | Alarm priority (0–1000) |
| `--setpoint` | yes | Setpoint value | | `--description` | no | Description |
| `--severity` | no | Alarm severity (default: `Warning`) | | `--trigger-config` | no | Trigger configuration as a JSON string (overrides typed flags when both are supplied) |
| `--notification-list` | no | Notification list name to notify on alarm | | `--locked` | no | Lock the alarm in derived templates |
| `--attribute` | no | Attribute name the trigger watches (all trigger types except `Expression`) |
| `--match-value` | no | `ValueMatch`: value to compare against |
| `--not-equals` | no | `ValueMatch`: match when the value is NOT equal |
| `--min` | no | `RangeViolation`: minimum allowed value |
| `--max` | no | `RangeViolation`: maximum allowed value |
| `--threshold-per-second` | no | `RateOfChange`: rate threshold per second |
| `--window-seconds` | no | `RateOfChange`: sliding window in seconds |
| `--direction` | no | `RateOfChange`: direction (`rising`, `falling`, or `either`) |
| `--lolo` | no | `HiLo`: low-low setpoint |
| `--lo` | no | `HiLo`: low setpoint |
| `--hi` | no | `HiLo`: high setpoint |
| `--hihi` | no | `HiLo`: high-high setpoint |
| `--expression` | no | `Expression`: boolean trigger expression |
#### `template alarm update` #### `template alarm update`
Update an alarm definition on a template. Update an alarm definition on a template. An update **replaces** the whole entity — every
required field below must be supplied with its post-update value, even if unchanged.
```sh ```sh
scadabridge --url <url> template alarm update --template-id <int> --name <string> [--condition <string>] [--setpoint <string>] [--severity <string>] [--notification-list <string>] scadabridge --url <url> template alarm update --id <int> --name <string> --trigger-type <string> --priority <int> [--description <string>] [--trigger-config <json>] [--locked]
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--template-id` | yes | Template ID | | `--id` | yes | Alarm ID |
| `--name` | yes | Alarm name to update | | `--name` | yes | Alarm name |
| `--condition` | no | Updated trigger condition | | `--trigger-type` | yes | Trigger type |
| `--setpoint` | no | Updated setpoint value | | `--priority` | yes | Alarm priority (0–1000) |
| `--severity` | no | Updated severity | | `--description` | no | Description |
| `--notification-list` | no | Updated notification list name | | `--trigger-config` | no | Trigger configuration JSON |
| `--locked` | no | Lock the alarm in derived templates |
#### `template alarm delete` #### `template alarm delete`
Remove an alarm definition from a template. Remove an alarm definition from a template.
```sh ```sh
scadabridge --url <url> template alarm delete --template-id <int> --name <string> scadabridge --url <url> template alarm delete --id <int>
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--template-id` | yes | Template ID | | `--id` | yes | Alarm ID |
| `--name` | yes | Alarm name to delete |
#### `template native-alarm-source add` #### `template native-alarm-source add`
@@ -309,60 +323,64 @@ scadabridge --url <url> template native-alarm-source remove --id <int>
Add a script to a template. Add a script to a template.
```sh ```sh
scadabridge --url <url> template script add --template-id <int> --name <string> --trigger-type <string> [--trigger-attribute <string>] [--interval <int>] --code <string> scadabridge --url <url> template script add --template-id <int> --name <string> --trigger-type <string> --code <string> [--trigger-config <json>] [--locked] [--parameters <json>] [--return-def <json>]
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--template-id` | yes | Template ID | | `--template-id` | yes | Template ID |
| `--name` | yes | Script name | | `--name` | yes | Script name |
| `--trigger-type` | yes | Trigger type: `OnChange`, `Periodic`, `OnAlarm` | | `--trigger-type` | yes | Trigger type (e.g. `OnChange`, `Periodic`, `OnAlarm`) |
| `--trigger-attribute` | no | Attribute name for `OnChange` trigger | | `--code` | yes | Script source code |
| `--interval` | no | Interval in milliseconds for `Periodic` trigger | | `--trigger-config` | no | Trigger configuration as a JSON string (e.g. interval, attribute name) |
| `--code` | yes | Script source code (or `@filepath` to read from file) | | `--locked` | no | Lock the script in derived templates |
| `--parameters` | no | Parameter definitions JSON |
| `--return-def` | no | Return definition JSON |
#### `template script update` #### `template script update`
Update a script on a template. Update a script on a template. An update **replaces** the whole entity — every required
field below must be supplied with its post-update value, even if unchanged.
```sh ```sh
scadabridge --url <url> template script update --template-id <int> --name <string> [--trigger-type <string>] [--trigger-attribute <string>] [--interval <int>] [--code <string>] scadabridge --url <url> template script update --id <int> --name <string> --trigger-type <string> --code <string> [--trigger-config <json>] [--locked] [--parameters <json>] [--return-def <json>]
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--template-id` | yes | Template ID | | `--id` | yes | Script ID |
| `--name` | yes | Script name to update | | `--name` | yes | Script name |
| `--trigger-type` | no | Updated trigger type | | `--trigger-type` | yes | Trigger type |
| `--trigger-attribute` | no | Updated trigger attribute | | `--code` | yes | Script source code |
| `--interval` | no | Updated interval | | `--trigger-config` | no | Trigger configuration JSON |
| `--code` | no | Updated script source code (or `@filepath`) | | `--locked` | no | Lock the script in derived templates |
| `--parameters` | no | Parameter definitions JSON |
| `--return-def` | no | Return definition JSON |
#### `template script delete` #### `template script delete`
Remove a script from a template. Remove a script from a template.
```sh ```sh
scadabridge --url <url> template script delete --template-id <int> --name <string> scadabridge --url <url> template script delete --id <int>
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--template-id` | yes | Template ID | | `--id` | yes | Script ID |
| `--name` | yes | Script name to delete |
#### `template composition add` #### `template composition add`
Add a feature module composition to a template. Add a feature module composition to a template.
```sh ```sh
scadabridge --url <url> template composition add --template-id <int> --module-template-id <int> --instance-name <string> scadabridge --url <url> template composition add --template-id <int> --composed-template-id <int> --instance-name <string>
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--template-id` | yes | Target template ID | | `--template-id` | yes | Target template ID |
| `--module-template-id` | yes | Feature module template ID to compose | | `--composed-template-id` | yes | Feature module template ID to compose |
| `--instance-name` | yes | Instance name for the composed module (used in path-qualified addressing) | | `--instance-name` | yes | Instance name for the composed module (used in path-qualified addressing) |
#### `template composition delete` #### `template composition delete`
@@ -508,6 +526,84 @@ scadabridge --url <url> instance set-bindings --id <int> --bindings <json>
| `--id` | yes | Instance ID | | `--id` | yes | Instance ID |
| `--bindings` | yes | JSON array of `[attributeName, dataConnectionId]` pairs (e.g. `[["Speed",7],["Temperature",7]]`) | | `--bindings` | yes | JSON array of `[attributeName, dataConnectionId]` pairs (e.g. `[["Speed",7],["Temperature",7]]`) |
#### `instance set-overrides`
Set attribute value overrides for an instance.
```sh
scadabridge --url <url> instance set-overrides --id <int> --overrides <json>
```
| Option | Required | Description |
|--------|----------|-------------|
| `--id` | yes | Instance ID |
| `--overrides` | yes | JSON object of attribute name to value (e.g. `{"Speed": "100", "Mode": null}`); null clears an override |
#### `instance alarm-override set`
Set (upsert) an alarm override on an instance.
```sh
scadabridge --url <url> instance alarm-override set --instance-id <int> --alarm <string> [--trigger-config <json>] [--priority <int>]
```
| Option | Required | Description |
|--------|----------|-------------|
| `--instance-id` | yes | Instance ID |
| `--alarm` | yes | Alarm canonical name (e.g. `TempLevels` or `Pump.TempSensor.Heat`) |
| `--trigger-config` | no | JSON override for TriggerConfiguration (HiLo: partial merge; others: whole-replace) |
| `--priority` | no | Priority override (0–1000) |
#### `instance alarm-override delete`
Remove an alarm override on an instance.
```sh
scadabridge --url <url> instance alarm-override delete --instance-id <int> --alarm <string>
```
| Option | Required | Description |
|--------|----------|-------------|
| `--instance-id` | yes | Instance ID |
| `--alarm` | yes | Alarm canonical name |
#### `instance alarm-override list`
List all alarm overrides for an instance.
```sh
scadabridge --url <url> instance alarm-override list --instance-id <int>
```
| Option | Required | Description |
|--------|----------|-------------|
| `--instance-id` | yes | Instance ID |
#### `instance set-area`
Reassign an instance to a different area (or clear its area assignment).
```sh
scadabridge --url <url> instance set-area --id <int> [--area-id <int>]
```
| Option | Required | Description |
|--------|----------|-------------|
| `--id` | yes | Instance ID |
| `--area-id` | no | Area ID; omit to clear area assignment |
#### `instance diff`
Show the deployment diff between the currently deployed configuration and the current template state.
```sh
scadabridge --url <url> instance diff --id <int>
```
| Option | Required | Description |
|--------|----------|-------------|
| `--id` | yes | Instance ID |
--- ---
### `site` — Manage sites ### `site` — Manage sites
@@ -537,7 +633,7 @@ scadabridge --url <url> site list
Register a new site. Register a new site.
```sh ```sh
scadabridge --url <url> site create --name <string> --identifier <string> [--description <string>] scadabridge --url <url> site create --name <string> --identifier <string> [--description <string>] [--node-a-address <string>] [--node-b-address <string>] [--grpc-node-a-address <string>] [--grpc-node-b-address <string>]
``` ```
| Option | Required | Description | | Option | Required | Description |
@@ -545,6 +641,29 @@ scadabridge --url <url> site create --name <string> --identifier <string> [--des
| `--name` | yes | Human-readable site name | | `--name` | yes | Human-readable site name |
| `--identifier` | yes | Unique machine identifier used for cluster routing (e.g. `site-a`) | | `--identifier` | yes | Unique machine identifier used for cluster routing (e.g. `site-a`) |
| `--description` | no | Site description | | `--description` | no | Site description |
| `--node-a-address` | no | Akka.NET cluster address for Node A |
| `--node-b-address` | no | Akka.NET cluster address for Node B |
| `--grpc-node-a-address` | no | gRPC streaming address for Node A |
| `--grpc-node-b-address` | no | gRPC streaming address for Node B |
#### `site update`
Update an existing site. An update **replaces** the whole entity — every required field
below must be supplied with its post-update value, even if unchanged.
```sh
scadabridge --url <url> site update --id <int> --name <string> [--description <string>] [--node-a-address <string>] [--node-b-address <string>] [--grpc-node-a-address <string>] [--grpc-node-b-address <string>]
```
| Option | Required | Description |
|--------|----------|-------------|
| `--id` | yes | Site ID |
| `--name` | yes | Human-readable site name |
| `--description` | no | Site description |
| `--node-a-address` | no | Akka.NET cluster address for Node A |
| `--node-b-address` | no | Akka.NET cluster address for Node B |
| `--grpc-node-a-address` | no | gRPC streaming address for Node A |
| `--grpc-node-b-address` | no | gRPC streaming address for Node B |
#### `site delete` #### `site delete`
@@ -587,14 +706,14 @@ scadabridge --url <url> site area list --site-id <int>
Create an area within a site. Create an area within a site.
```sh ```sh
scadabridge --url <url> site area create --site-id <int> --name <string> [--parent-area-id <int>] scadabridge --url <url> site area create --site-id <int> --name <string> [--parent-id <int>]
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--site-id` | yes | Site ID | | `--site-id` | yes | Site ID |
| `--name` | yes | Area name | | `--name` | yes | Area name |
| `--parent-area-id` | no | Parent area ID for nested areas | | `--parent-id` | no | Parent area ID for nested areas |
#### `site area update` #### `site area update`
@@ -885,17 +1004,18 @@ scadabridge --url <url> notification smtp list
Update the SMTP configuration. Update the SMTP configuration.
```sh ```sh
scadabridge --url <url> notification smtp update --host <string> --port <int> --auth-type <string> [--username <string>] [--password <string>] [--from-address <string>] scadabridge --url <url> notification smtp update --id <int> --server <string> --port <int> --auth-mode <string> --from-address <string> [--tls-mode <string>] [--credentials <string>]
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--host` | yes | SMTP server hostname | | `--id` | yes | SMTP config ID |
| `--server` | yes | SMTP server hostname |
| `--port` | yes | SMTP server port | | `--port` | yes | SMTP server port |
| `--auth-type` | yes | Authentication type: `OAuth2` or `Basic` | | `--auth-mode` | yes | Authentication mode (e.g. `OAuth2ClientCredentials`, `Basic`) |
| `--username` | no | SMTP username (for Basic auth) | | `--from-address` | yes | Sender email address |
| `--password` | no | SMTP password (for Basic auth) | | `--tls-mode` | no | TLS mode: `None`, `StartTLS`, or `SSL` (preserves existing if omitted) |
| `--from-address` | no | Sender email address | | `--credentials` | no | SMTP credentials — `username:password` for Basic, or client secret for OAuth2 (preserves existing if omitted) |
--- ---
@@ -914,38 +1034,51 @@ scadabridge --url <url> security api-key list
Create a new inbound API key. The generated key value is returned in the response and not stored in plaintext — save it immediately. Create a new inbound API key. The generated key value is returned in the response and not stored in plaintext — save it immediately.
```sh ```sh
scadabridge --url <url> security api-key create --name <string> scadabridge --url <url> security api-key create --name <string> --methods <string>
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--name` | yes | Descriptive label for the key | | `--name` | yes | Descriptive label for the key |
| `--methods` | yes | Comma-separated API method names this key may call (e.g. `"MethodA,MethodB"`) |
#### `security api-key update` #### `security api-key update`
Update an API key's name or enabled status. Enable or disable an API key.
```sh ```sh
scadabridge --url <url> security api-key update --id <int> [--name <string>] [--enabled <bool>] scadabridge --url <url> security api-key update --key-id <string> --enabled <bool>
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--id` | yes | API key ID | | `--key-id` | yes | API key ID |
| `--name` | no | Updated label | | `--enabled` | yes | Enable or disable the key (`true` or `false`) |
| `--enabled` | no | Enable or disable the key (`true` or `false`) |
#### `security api-key set-methods`
Replace the method scopes on an existing API key.
```sh
scadabridge --url <url> security api-key set-methods --key-id <string> --methods <string>
```
| Option | Required | Description |
|--------|----------|-------------|
| `--key-id` | yes | API key ID |
| `--methods` | yes | Comma-separated API method names (replaces the existing set) |
#### `security api-key delete` #### `security api-key delete`
Revoke and delete an API key. Revoke and delete an API key.
```sh ```sh
scadabridge --url <url> security api-key delete --id <int> scadabridge --url <url> security api-key delete --key-id <string>
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--id` | yes | API key ID | | `--key-id` | yes | API key ID |
#### `security role-mapping list` #### `security role-mapping list`
@@ -997,27 +1130,27 @@ scadabridge --url <url> security role-mapping delete --id <int>
#### `security scope-rule list` #### `security scope-rule list`
List all site scope rules for role mappings. List all site scope rules for a role mapping.
```sh ```sh
scadabridge --url <url> security scope-rule list [--role-mapping-id <int>] scadabridge --url <url> security scope-rule list --mapping-id <int>
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--role-mapping-id` | no | Filter by role mapping ID | | `--mapping-id` | yes | Role mapping ID |
#### `security scope-rule add` #### `security scope-rule add`
Add a site scope rule to a role mapping, restricting it to a specific site. Add a site scope rule to a role mapping, restricting it to a specific site.
```sh ```sh
scadabridge --url <url> security scope-rule add --role-mapping-id <int> --site-id <int> scadabridge --url <url> security scope-rule add --mapping-id <int> --site-id <int>
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--role-mapping-id` | yes | Role mapping ID | | `--mapping-id` | yes | Role mapping ID |
| `--site-id` | yes | Site ID to scope the mapping to | | `--site-id` | yes | Site ID to scope the mapping to |
#### `security scope-rule delete` #### `security scope-rule delete`
@@ -1061,29 +1194,32 @@ scadabridge --url <url> health site --identifier <string>
Query the site event log for a specific site. Events are fetched remotely from the site's local SQLite store. Query the site event log for a specific site. Events are fetched remotely from the site's local SQLite store.
```sh ```sh
scadabridge --url <url> health event-log --site-identifier <string> [--from <datetime>] [--to <datetime>] [--search <string>] [--page <int>] [--page-size <int>] scadabridge --url <url> health event-log --site <string> [--event-type <string>] [--severity <string>] [--keyword <string>] [--from <datetime>] [--to <datetime>] [--page <int>] [--page-size <int>] [--instance-name <string>]
``` ```
| Option | Required | Default | Description | | Option | Required | Default | Description |
|--------|----------|---------|-------------| |--------|----------|---------|-------------|
| `--site-identifier` | yes | — | Site identifier | | `--site` | yes | — | Site identifier |
| `--event-type` | no | — | Filter by event type |
| `--severity` | no | — | Filter by severity |
| `--keyword` | no | — | Keyword search term |
| `--from` | no | — | Start timestamp in ISO 8601 format | | `--from` | no | — | Start timestamp in ISO 8601 format |
| `--to` | no | — | End timestamp in ISO 8601 format | | `--to` | no | — | End timestamp in ISO 8601 format |
| `--search` | no | — | Keyword search term |
| `--page` | no | `1` | Page number | | `--page` | no | `1` | Page number |
| `--page-size` | no | `50` | Results per page | | `--page-size` | no | `50` | Results per page |
| `--instance-name` | no | — | Filter by instance name |
#### `health parked-messages` #### `health parked-messages`
Query parked (dead-letter) messages at a specific site. Query parked (dead-letter) messages at a specific site.
```sh ```sh
scadabridge --url <url> health parked-messages --site-identifier <string> [--page <int>] [--page-size <int>] scadabridge --url <url> health parked-messages --site <string> [--page <int>] [--page-size <int>]
``` ```
| Option | Required | Default | Description | | Option | Required | Default | Description |
|--------|----------|---------|-------------| |--------|----------|---------|-------------|
| `--site-identifier` | yes | — | Site identifier | | `--site` | yes | — | Site identifier |
| `--page` | no | `1` | Page number | | `--page` | no | `1` | Page number |
| `--page-size` | no | `50` | Results per page | | `--page-size` | no | `50` | Results per page |
@@ -1162,6 +1298,8 @@ scadabridge --url <url> audit query [options]
| `--target` | no | — | Filter by target (external system, DB connection, notification list) | | `--target` | no | — | Filter by target (external system, DB connection, notification list) |
| `--actor` | no | — | Filter by actor | | `--actor` | no | — | Filter by actor |
| `--correlation-id` | no | — | Filter by correlation ID | | `--correlation-id` | no | — | Filter by correlation ID |
| `--execution-id` | no | — | Filter by execution ID |
| `--parent-execution-id` | no | — | Filter by parent execution ID |
| `--errors-only` | no | `false` | Show only failed events (`status=Failed`; overrides `--status`) | | `--errors-only` | no | `false` | Show only failed events (`status=Failed`; overrides `--status`) |
| `--page-size` | no | `100` | Events per page (1–1000) | | `--page-size` | no | `100` | Events per page (1–1000) |
| `--all` | no | `false` | Fetch every page, following the keyset cursor | | `--all` | no | `false` | Fetch every page, following the keyset cursor |
@@ -1350,14 +1488,13 @@ scadabridge --url <url> db-connection get --id <int>
Create a new database connection definition. Create a new database connection definition.
```sh ```sh
scadabridge --url <url> db-connection create --name <string> --connection-string <string> [--provider <string>] scadabridge --url <url> db-connection create --name <string> --connection-string <string>
``` ```
| Option | Required | Description | | Option | Required | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `--name` | yes | Connection name | | `--name` | yes | Connection name |
| `--connection-string` | yes | Database connection string | | `--connection-string` | yes | Database connection string |
| `--provider` | no | Database provider (default: `SqlServer`) |
#### `db-connection update` #### `db-connection update`
@@ -1415,14 +1552,16 @@ scadabridge --url <url> api-method get --id <int>
Create a new inbound API method. Create a new inbound API method.
```sh ```sh
scadabridge --url <url> api-method create --name <string> --code <string> [--description <string>] scadabridge --url <url> api-method create --name <string> --script <string> [--timeout <int>] [--parameters <json>] [--return-def <json>]
``` ```
| Option | Required | Description | | Option | Required | Default | Description |
|--------|----------|-------------| |--------|----------|---------|-------------|
| `--name` | yes | Method name (used as the URL path segment in `POST /api/{methodName}`) | | `--name` | yes | — | Method name (used as the URL path segment in `POST /api/{methodName}`) |
| `--code` | yes | Script source code implementing the method (or `@filepath` to read from file) | | `--script` | yes | — | Script source code implementing the method |
| `--description` | no | Method description | | `--timeout` | no | `30` | Timeout in seconds |
| `--parameters` | no | — | Parameter definitions JSON |
| `--return-def` | no | — | Return type definition JSON |
#### `api-method update` #### `api-method update`
@@ -1457,6 +1596,74 @@ scadabridge --url <url> api-method delete --id <int>
--- ---
### `bundle` — Transport bundle export / preview / import
Export, preview, and import Transport (#24) bundles. Bundles carry templates, shared
scripts, external systems, database connections, notification lists, SMTP configurations,
and API methods between environments. Inbound API keys are **not** transported — recreate
them on the destination via the CLI or UI.
Bundle commands use a 5-minute timeout (larger payloads may be slow over WAN).
#### `bundle export`
Export selected entities to a `.scadabundle` file.
```sh
scadabridge --url <url> bundle export --output <path> [--passphrase <string>] [--all] [--include-dependencies] [entity-selectors]
```
| Option | Required | Description |
|--------|----------|-------------|
| `--output` | yes | Output file path (e.g. `env-baseline.scadabundle`) |
| `--passphrase` | no | Encryption passphrase; omit to produce an unencrypted bundle |
| `--all` | no | Export every entity of every supported type (ignores per-type name flags) |
| `--include-dependencies` | no | Pull transitive dependencies (referenced shared scripts, parents, composed members) into the bundle |
| `--templates` | no | Comma-separated template names to include |
| `--shared-scripts` | no | Comma-separated shared-script names to include |
| `--external-systems` | no | Comma-separated external-system names to include |
| `--db-connections` | no | Comma-separated database-connection names to include |
| `--notification-lists` | no | Comma-separated notification-list names to include |
| `--smtp-configs` | no | Comma-separated SMTP host names to include |
| `--api-methods` | no | Comma-separated API-method names to include |
| `--source-environment` | no | `SourceEnvironment` value stamped into the bundle manifest (default: `cli`) |
**Example** — export two templates and all their dependencies:
```sh
scadabridge --url <url> bundle export --output baseline.scadabundle \
--templates "PumpTemplate,TankTemplate" --include-dependencies
```
#### `bundle preview`
Load a bundle and print the diff preview (Added / Modified / Unchanged per entity) without applying any changes.
```sh
scadabridge --url <url> bundle preview --input <path> [--passphrase <string>]
```
| Option | Required | Description |
|--------|----------|-------------|
| `--input` | yes | Bundle file path (`.scadabundle`) |
| `--passphrase` | no | Passphrase for encrypted bundles |
#### `bundle import`
Load and apply a bundle with a single global conflict policy. Preview first with `bundle preview` to review the diff.
```sh
scadabridge --url <url> bundle import --input <path> [--passphrase <string>] [--on-conflict <policy>]
```
| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `--input` | yes | — | Bundle file path (`.scadabundle`) |
| `--passphrase` | no | — | Passphrase for encrypted bundles |
| `--on-conflict` | no | `overwrite` | Resolution policy for `Modified` rows: `skip`, `overwrite`, or `rename` |
---
## Architecture Notes ## Architecture Notes
The CLI connects to the Central cluster using Akka.NET's `ClusterClient`. It does not join the cluster — it contacts the `ClusterClientReceptionist` on one of the configured Central nodes and sends commands to the `ManagementActor` at path `/user/management`. The CLI connects to the Central cluster using Akka.NET's `ClusterClient`. It does not join the cluster — it contacts the `ClusterClientReceptionist` on one of the configured Central nodes and sends commands to the `ManagementActor` at path `/user/management`.