wwtools/graccesscli/docs/usage.md

GRAccess CLI Usage

Command-line interface for Aveva System Platform Galaxy management via the GRAccess library.

Global Options

All commands that interact with a galaxy require:

Option	Short	Description	Required
--galaxy	-g	Galaxy name	Yes
--node	-n	GR node name. Blank defaults to local node; . is normalized to the local machine name.	One-shot mode only

In session mode, --node is not needed because the daemon already holds the connection.

Machine-facing commands also support:

Option	Description
--json	Legacy command-specific JSON. Existing shapes are preserved.
--llm-json	Stable success/error envelope for LLM and tool callers.
--dry-run	For mutating routed commands, validate arguments and confirmation without invoking mutating GRAccess calls.

--llm-json envelope shape:

{
  "success": true,
  "command": "object get",
  "galaxy": "ZB",
  "target": "TestMachine",
  "data": {},
  "commandResult": null,
  "warnings": [],
  "unavailable": [],
  "error": null,
  "exitCode": 0
}

LLM And Tooling Commands

capabilities

Return the code-backed command registry.

graccess capabilities --json
graccess capabilities --llm-json

The registry includes command names, arguments, mutation status, session routing support, confirmation target rules, and output schema names.

validate

Validate a single-command or batch plan file without connecting to GRAccess.

graccess validate --request plan.json --llm-json

batch

Validate or execute a command plan. Execution stops on first failure. Every mutating step must include its own confirm=true and exact confirm-target.

graccess batch --file plan.json --mode validate --llm-json
graccess batch --file plan.json --mode execute --llm-json

Plan example:

{
  "Galaxy": "ZB",
  "Node": ".",
  "Commands": [
    {
      "Command": "object attribute value set",
      "Args": {
        "name": "TestMachine",
        "type": "template",
        "attribute": "Description",
        "value": "Updated",
        "data-type": "string",
        "confirm": true,
        "confirm-target": "TestMachine"
      }
    }
  ]
}

Galaxy Commands

galaxy list

List available galaxies on a GR node.

graccess galaxy list [--node <node>] [--json] [--llm-json]

Option	Short	Required	Description
--node	-n	No	GR node name to query. Blank defaults to local node; . is normalized to the local machine name.
--json		No	Output as JSON array
--llm-json		No	Output stable LLM envelope

This command always runs in one-shot mode (no galaxy login needed). It does not use or require an active session.

Example output:

MyGalaxy1
MyGalaxy2
TestGalaxy

With --json:

[
  "MyGalaxy1",
  "MyGalaxy2",
  "TestGalaxy"
]

---

Object Query Commands

These commands route through an active session when one exists for the target galaxy. Without an active session, they connect to a galaxy, run a read-only GRAccess query, and disconnect. Name patterns use the GRAccess namedLike condition; use % as the wildcard.

object list

List templates, instances, or both.

graccess object list --galaxy <name> --node <node> [--type all|template|instance] [--pattern <pattern>] [--json]

Option	Short	Default	Description
--galaxy	-g	(required)	Galaxy name
--node	-n	local node	GR node name. . is normalized to the local machine name.
--type	-t	all	Object type: all, template, or instance
--pattern	-p	%	GRAccess name pattern. Use % as wildcard.
--json		false	Output as JSON

Example:

graccess object list --galaxy ZB --node . --type instance --pattern 'TestMachine_%'

template list

List templates.

graccess template list --galaxy <name> --node <node> [--pattern <pattern>] [--json]

instance list

List instances.

graccess instance list --galaxy <name> --node <node> [--pattern <pattern>] [--json]

Example:

graccess instance list --galaxy ZB --node . --pattern '%'

object attributes

List attributes for a template or instance.

graccess object attributes --galaxy <name> --node <node> --name <tagname> [--type all|template|instance] [--configurable] [--json]

Option	Short	Default	Description
--galaxy	-g	(required)	Galaxy name
--node	-n	local node	GR node name. . is normalized to the local machine name.
--name		(required)	Template or instance tagname
--type	-t	all	Object type: all, template, or instance
--configurable		false	Query ConfigurableAttributes instead of Attributes
--json		false	Output as JSON

Some optional COM-backed attribute properties are not available for every object. In JSON output those values are emitted as null; text output includes the stable name, data type, and category columns.

Example:

graccess object attributes --galaxy ZB --node . --name DEV --type instance --configurable

---

LLM Snapshot And IDE Commands

object snapshot

Return a bundled object snapshot for planning and verification.

graccess object snapshot --galaxy ZB --name TestMachine --type template --llm-json

Snapshot data includes object identity/status, all attributes, configurable attributes, extended attributes, relationships, lineage, children, contained objects, package-backed attribute values and script bodies where available, and unavailable field details.

Use snapshots, direct lineage commands, and relationship queries together to parse inheritance and containment:

graccess object snapshot --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object lineage --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object children --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object query-condition --galaxy ZB --type all --condition derivedOrInstantiatedFrom --value '$gMachine' --llm-json
graccess object query-condition --galaxy ZB --type all --condition basedOn --value '$gMachine' --llm-json
graccess object query-condition --galaxy ZB --type all --condition containedBy --value '$TestMachine' --llm-json
graccess object query-condition --galaxy ZB --type all --condition hierarchicalNameLike --value '%TestMachine%' --llm-json

object lineage walks typed ITemplate / IInstance relationship properties first and falls back to the read-only package snapshot when GRAccess export is available. object children combines package-backed containment with direct GRAccess scans for objects whose DerivedFrom, BasedOn, Container, or HierarchicalName point at the target.

When direct GRAccess does not expose a field, the CLI records a structured unavailable entry instead of guessing. Normal CLI usage does not query the Galaxy SQL database; SQL is allowed only for development verification/debugging outside the supported command path.

Attribute values

graccess object attribute value get --galaxy ZB --name TestMachine --type template --attribute Description --llm-json
graccess object attribute value set --galaxy ZB --name TestMachine --type template --attribute Description --value Updated --data-type string --confirm --confirm-target TestMachine --llm-json

Scalar string, bool, int, float, and double writes are supported first. Value reads try direct IAttribute.Value first, then use the read-only exported package fallback for scalar package values. Array and complex readback returns structured unavailable details unless parsed safely.

Object scripts

graccess object scripts list --galaxy ZB --name TestMachine --type template --llm-json
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt.ExecuteText --llm-json
graccess object scripts settings set --galaxy ZB --name '$TestMachine' --type template --script UpdateTestChangingInt --trigger-period-ms 500 --lock-trigger-period --confirm --confirm-target '$TestMachine' --llm-json
graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate' --llm-json

Direct object script body access depends on the local GRAccess object model. Reads inspect the exported package fallback for script extension bodies and script text fields such as ExecuteText, DeclarationsText, StartupText, ShutdownText, OnScanText, OffScanText, and Expression.

For writes, the CLI uses the public GRAccess path exposed by IgObject.ConfigurableAttributes[...] / Attributes[...] and IAttribute.SetValue. This is valid for mutable settings such as TriggerPeriod and TriggerType. MxElapsedTime values are stored in 100 ns increments, so --trigger-period-ms 500 writes 5,000,000.

Script body fields and Expression on the local ScriptExtension projection are package-only (MxCategoryPackageOnly*). GRAccess IAttribute.SetValue can report success for those fields without persisting the value, so the CLI now fails fast when it sees a package-only category. object scripts create can add the ScriptExtension primitive and initialize mutable settings, but it cannot initialize package-only body text through GRAccess. Use the IDE or a future package-rewrite path for body/expression edits.

Area, engine, assignment, and I/O wrappers

graccess area list --galaxy ZB --llm-json
graccess area create --galaxy ZB --template '$Area' --name Area_Test --confirm --confirm-target '$Area' --llm-json
graccess engine list --galaxy ZB --llm-json
graccess engine create --galaxy ZB --template '$AppEngine' --name AppEngine_Test --confirm --confirm-target '$AppEngine' --llm-json
graccess instance assign-area --galaxy ZB --name TestMachine_001 --area Area_Test --confirm --confirm-target TestMachine_001 --llm-json
graccess instance assign-engine --galaxy ZB --name TestMachine_001 --engine AppEngine_Test --confirm --confirm-target TestMachine_001 --llm-json
graccess instance assign-container --galaxy ZB --name TestMachine_001 --container ParentObject --confirm --confirm-target TestMachine_001 --llm-json
graccess io assign --galaxy ZB --name TestMachine_001 --attribute DeviceAddress --value D100 --confirm --confirm-target TestMachine_001 --llm-json

object set --property area|host|container|toolset|security-group resolves named GRAccess objects before falling back to string assignment.

instance assign-engine sets the host when the object model accepts a direct engine host. If the instance is already assigned to an area hosted by that engine, the command treats that state as successful because some GRAccess object families use the area as the assignable host.

Extending templates and embedded objects

Use template derive to extend an existing template:

graccess template derive --galaxy ZB --name '$gMachine' --type template --new-name '$MyMachine' --confirm --confirm-target '$gMachine' --llm-json

Use --create-contained when deriving or instantiating a template family whose embedded objects should come along:

graccess template derive --galaxy ZB --name '$TestMachine' --type template --new-name '$MyMachine' --create-contained --confirm --confirm-target '$TestMachine' --llm-json
graccess template instantiate --galaxy ZB --name '$TestMachine' --type template --new-name TestMachine_021 --create-contained --confirm --confirm-target '$TestMachine' --llm-json

template delete --force-option defaults to dontForceTemplateDelete, which fails when instances exist instead of cascading. instance delete --force-option defaults to undeployIfDeployed so cleanup can remove deployed test instances after confirmation. object uda add and object uda update default --category to MxCategoryWriteable_USC; GRAccess builds that reject non-lockable UDA categories are normalized to MxCategoryWriteable_USC_Lockable at the COM call. Pass another valid MxAttributeCategory explicitly when a configure-only or calculated category is required. object extension add/delete pass typed extension calls to GRAccess; the legacy AnalogLimitAlarm extension type is accepted as an alias for the local AnalogExtension primitive type.

Single-object UDA, extension, attribute, script, and I/O mutations are atomic: the CLI checks out the object, applies the mutation, saves, and checks it back in. If the mutation or save fails after checkout, the CLI attempts UndoCheckOut before returning the original error. The explicit object checkout/save/checkin and objects checkout/checkin commands remain available for manual lifecycle operations.

Contained templates and child instances are edited as normal objects by targeting their own tagname:

graccess object snapshot --galaxy ZB --name '$TestMachine.DelmiaReceiver' --type template --llm-json
graccess object snapshot --galaxy ZB --name DelmiaReceiver_001 --type instance --llm-json
graccess object checkout --galaxy ZB --name DelmiaReceiver_001 --type instance --confirm --confirm-target DelmiaReceiver_001
graccess object attribute value set --galaxy ZB --name DelmiaReceiver_001 --type instance --attribute DownloadPath --value 'C:\Recipes\001' --data-type string --confirm --confirm-target DelmiaReceiver_001 --llm-json
graccess object save --galaxy ZB --name DelmiaReceiver_001 --type instance --confirm --confirm-target DelmiaReceiver_001
graccess object checkin --galaxy ZB --name DelmiaReceiver_001 --type instance --comment 'Configure embedded receiver' --confirm --confirm-target DelmiaReceiver_001

Use instance assign-container or object set --property container only after confirming the object model allows moving/reparenting that child.

---

Session Management

Session mode keeps a GRAccess connection open in a background daemon process, avoiding expensive reconnection on each CLI invocation.

session start

Start a background session for a galaxy.

graccess session start --galaxy <name> --node <node> [--idle-timeout <minutes>]

Option	Default	Description
--galaxy, -g	(required)	Galaxy name
--node, -n	(required)	GR node name. . is normalized to the local machine name.
--idle-timeout	30	Minutes of inactivity before auto-shutdown

Behavior:

• Spawns a background daemon process
• Waits up to 90 seconds for the daemon to connect and become ready
• If a session is already running for this galaxy, reports the existing PID
• Daemon logs to %LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\logs\daemon-{galaxy}.log

session stop

Stop a running session.

graccess session stop --galaxy <name>

Sends a shutdown signal to the daemon via named pipe. The daemon disconnects from the galaxy and exits.

session status

Check if a session is running.

graccess session status --galaxy <name>

Output includes: galaxy name, node, PID, start time, and pipe name. Automatically cleans up stale session files from crashed daemons.

Execution Modes

Session mode (fast)

When a session is active, commands route through the daemon automatically:

graccess session start --galaxy MyGalaxy --node MyNode
graccess <command> --galaxy MyGalaxy [options]        # routed via named pipe
graccess <command> --galaxy MyGalaxy [options]        # reuses same connection
graccess session stop --galaxy MyGalaxy

One-shot mode (no session)

Without an active session, commands open a direct connection, execute, and disconnect:

graccess <command> --galaxy MyGalaxy --node MyNode [options]

This is slower but requires no setup. The --node option is required in one-shot mode.

Routing logic

The CommandRouter checks for an active session first:

1. Look up session info file at %LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\sessions\{galaxy}.json
2. Verify the daemon process is alive (PID check)
3. If alive, send command as JSON via named pipe graccess-session-{galaxy}
4. If no session, fall back to one-shot mode (requires --node)

Currently routed through the session daemon:

• object list
• template list
• instance list
• object attributes
• All other logged-in galaxy commands added under galaxy, object, template, instance, objects, toolset, script-library, security, and settings.

Pre-login galaxy administration commands remain one-shot because they operate before a galaxy session exists:

• galaxy list
• galaxy create
• galaxy create-from-template
• galaxy delete

Expanded Command Surface

The CLI exposes the GRAccess operations listed in graccess_operations.md through these command families:

Family	Commands
Galaxy	galaxy info, galaxy sync, galaxy cdi-version, galaxy defaults get/set, galaxy backup/restore/migrate, galaxy import-objects, galaxy import-objects-ex, galaxy import-script-library, galaxy export-all, galaxy grload, galaxy create, galaxy create-from-template, galaxy delete
Objects	object get, object snapshot, object lineage, object children, object query-name, object query-condition, object query-multi, object extended-attributes, object help-url, object scripts list/get/set, object checkout/checkin/undo-checkout/save/unload/set
Templates and instances	template derive, template instantiate, template delete, instance delete/deploy/undeploy/upload, instance assign-area/assign-engine/assign-container
Attributes, UDAs, extensions	object attribute get/set/value get/value set/lock/security/buffer, object uda add/delete/rename/update, object extension add/delete/rename
Bulk objects	objects checkout/checkin/undo-checkout/deploy/undeploy/upload/delete/export/export-protected
IDE wrappers and tooling	capabilities, validate, batch, area list/create, engine list/create, io assign
Toolsets/scripts/security/settings	toolset list/tree/add/delete/rename/move, script-library list/add/import/export, security info/roles/users/groups/permissions, settings locale get, settings time-master get

Mutating commands require --confirm. Mutating commands also validate --confirm-target against the exact object, galaxy, bulk target list, or file target used by the command.

IPC Protocol

Communication between CLI and daemon uses newline-delimited JSON over named pipes.

Request format

{"type":"execute","command":"<cmd>","subcommand":"<subcmd>","args":{"key":"value"}}

Request types: execute, shutdown, status

Response format

{"success":true,"output":"...","exitCode":0}
{"success":false,"error":"...","exitCode":1}

Daemon Details

• Pipe name: graccess-session-{galaxyname} (lowercase)
• Mutex: Global\graccess-session-{galaxyname} (prevents duplicate daemons per galaxy)
• Session file: %LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\sessions\{galaxy}.json
• Log file: %LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\logs\daemon-{galaxy}.log (daily rolling, 7 day retention)
• Idle timeout: Checked every 30 seconds; daemon self-exits when exceeded
• COM threading: All GRAccess calls run on a dedicated STA thread with a Win32 message pump (StaComThread)