wwtools/graccesscli/docs/script-editing.md

Editing Scripts And Script Libraries

This guide describes how to edit scripts related to a template such as TestMachine.

Read script-parsing.md first so you know whether the target script is a script library, an object-level script-like attribute, an extension primitive, or content that only appears in an exported object package.

Run commands from graccess_cli. Examples assume an active session:

graccess session start --galaxy ZB --node .

Without a session, add --node . to each command.

For LLM-driven script work, read script metadata and validate guarded edits with the LLM envelope:

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 set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --file .\UpdateTestChangingInt.txt --confirm --confirm-target TestMachine --dry-run --llm-json

What The CLI Can Edit Today

Area	Current command support
Script library inventory	script-library list
Script library export	script-library export
Script library import/add	script-library import, script-library add, galaxy import-script-library
Object script metadata	object scripts list, object scripts get
Object script body read/write	object scripts get, object scripts set for script body attributes such as ExecuteText
Script-like attributes	object attribute set, lock, security, buffer
Extension primitives	object extension add/delete/rename
Full object package script payloads	Use objects export and galaxy import-objects

Export Before Editing

Export script libraries before changing them:

$out = '.\template-snapshots\script-libraries-before'
New-Item -ItemType Directory -Force -Path $out | Out-Null

$libs = graccess script-library list --galaxy ZB --json | ConvertFrom-Json
foreach ($lib in $libs) {
  $name = $lib.Name
  $path = Join-Path $out "$name.aaslib"
  graccess script-library export --galaxy ZB --name $name --output $path --confirm --confirm-target $path
}

Export the template package when object-level scripts may be involved:

$pkg = '.\template-snapshots\TestMachine-before\TestMachine.aaPKG'
graccess objects export --galaxy ZB --type template --name TestMachine --output $pkg --confirm --confirm-target $pkg

Edit Script Libraries

Script library content is edited outside the CLI in the .aaslib file or source toolchain that creates it. Import the updated library after review:

graccess script-library import --galaxy ZB --path '.\scripts\CommonScripts.aaslib' --confirm --confirm-target '.\scripts\CommonScripts.aaslib'

The galaxy-level import command is also available:

graccess galaxy import-script-library --galaxy ZB --path '.\scripts\CommonScripts.aaslib' --confirm --confirm-target '.\scripts\CommonScripts.aaslib'

After import, list libraries again:

graccess script-library list --galaxy ZB --json

Edit Script-Like Attributes

Some templates store expressions, declarations, triggers, or script fragments in attributes. Find candidates:

$attrs = graccess object attributes --galaxy ZB --name TestMachine --type template --json | ConvertFrom-Json
$extended = graccess object extended-attributes --galaxy ZB --name TestMachine --type template --json | ConvertFrom-Json
$scripts = (@($attrs) + @($extended)) | Where-Object {
  $_.Name -match '(?i)script|execute|trigger|expression|declaration|startup|shutdown|scan'
} | Sort-Object Name -Unique

$scripts | Select-Object Name, DataType, Category, Locked

If the script-like setting is a scalar string attribute, edit it through the normal template edit flow. Script extension fields should be written through ConfigurableAttributes; the CLI does this automatically for object scripts set, object scripts settings set, and mutating object attribute commands. object scripts set is the convenience wrapper for script body attributes. A bare script name maps to .ExecuteText; explicit fields such as .StartupText, .OnScanText, or .Expression are preserved.

graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
graccess object scripts set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --file .\UpdateTestChangingInt.txt --confirm --confirm-target TestMachine
graccess object save --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
graccess object checkin --galaxy ZB --name TestMachine --type template --comment 'Update script text' --confirm --confirm-target TestMachine

Update periodic script settings and lock the interval for deployment inheritance:

graccess object checkout --galaxy ZB --name '$TestMachine' --type template --confirm --confirm-target '$TestMachine'
graccess object scripts settings set --galaxy ZB --name '$TestMachine' --type template --script UpdateTestChangingInt --trigger-period-ms 500 --lock-trigger-period --confirm --confirm-target '$TestMachine'
graccess object save --galaxy ZB --name '$TestMachine' --type template --confirm --confirm-target '$TestMachine'
graccess object checkin --galaxy ZB --name '$TestMachine' --type template --comment 'Set UpdateTestChangingInt interval to 500ms' --confirm --confirm-target '$TestMachine'

Verify with package-backed readback:

graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json

Edit Extension Primitives

When a script is represented by an extension primitive, use the extension commands for the primitive lifecycle:

graccess object checkout --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
graccess object extension add --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan --object-extension --confirm --confirm-target TestMachine
graccess object save --galaxy ZB --name TestMachine --type template --confirm --confirm-target TestMachine
graccess object checkin --galaxy ZB --name TestMachine --type template --comment 'Add script extension primitive' --confirm --confirm-target TestMachine

Rename:

graccess object extension rename --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan --new-name OnScan2 --object-extension --confirm --confirm-target TestMachine

Delete:

graccess object extension delete --galaxy ZB --name TestMachine --type template --extension-type ScriptExtension --primitive OnScan2 --object-extension --confirm --confirm-target TestMachine

These commands manage primitive structure. The IDE-oriented wrapper below creates the same ScriptExtension primitive and can initialize the body and common settings:

graccess object checkout --galaxy ZB --name '$MyTemplate' --type template --confirm --confirm-target '$MyTemplate'
graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --file .\OnScan.txt --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate'
graccess object save --galaxy ZB --name '$MyTemplate' --type template --confirm --confirm-target '$MyTemplate'
graccess object checkin --galaxy ZB --name '$MyTemplate' --type template --comment 'Add OnScan script' --confirm --confirm-target '$MyTemplate'

After adding a ScriptExtension primitive, set its body with object scripts set --script <primitiveName> or object scripts set --script <primitiveName>.ExecuteText.

Full-Fidelity Object Script Edits

When script bodies are only available inside the object package, use export/import:

1. Export the template package.
2. Edit with the supported vendor tooling or package workflow.
3. Import the updated package with explicit confirmation.
4. Re-parse and validate the template.

Export:

$pkg = '.\template-work\TestMachine.aaPKG'
graccess objects export --galaxy ZB --type template --name TestMachine --output $pkg --confirm --confirm-target $pkg

Import:

graccess galaxy import-objects --galaxy ZB --file '.\template-work\TestMachine.aaPKG' --overwrite --confirm --confirm-target '.\template-work\TestMachine.aaPKG'

For conflict-aware import:

graccess galaxy import-objects-ex --galaxy ZB --file '.\template-work\TestMachine.aaPKG' --version-conflict '<E_RESOLVE_VERSION_CONFLICT_ACTION>' --name-conflict '<E_RESOLVE_NAME_CONFLICT_ACTION>' --confirm --confirm-target '.\template-work\TestMachine.aaPKG'

The exact enum values for import conflict handling must match the local GRAccess interop assembly. See graccess_operations.md and graccess_documentation.md.

Validate Script Edits

After import or checkin:

graccess object get --galaxy ZB --name TestMachine --type template --json
graccess object attributes --galaxy ZB --name TestMachine --type template --json
graccess object extended-attributes --galaxy ZB --name TestMachine --type template --json

For runtime validation, instantiate a test object and deploy only that explicitly named test instance:

graccess template instantiate --galaxy ZB --name TestMachine --type template --new-name TestMachine_ScriptTest_001 --create-contained --confirm --confirm-target TestMachine
graccess instance deploy --galaxy ZB --name TestMachine_ScriptTest_001 --type instance --confirm --confirm-target TestMachine_ScriptTest_001

Supported Object Script Command Pattern

graccess object scripts list --galaxy ZB --name TestMachine --type template --json
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json
graccess object scripts set --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --file .\UpdateTestChangingInt.txt --confirm --confirm-target TestMachine --llm-json

The local GRAccess examples sometimes show Template.Scripts[index].ScriptString. This repository's installed interop exposes the same practical content through script extension attributes such as UpdateTestChangingInt.ExecuteText; the CLI writes those attributes directly via IAttribute.SetValue.