systemlink-cli 1.27.1__tar.gz → 1.27.2__tar.gz

{systemlink_cli-1.27.1 → systemlink_cli-1.27.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: systemlink-cli
-Version: 1.27.1
+Version: 1.27.2
 Summary: SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates.
 License-File: LICENSE
 Author: Fred Visser

{systemlink_cli-1.27.1 → systemlink_cli-1.27.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "systemlink-cli"
-version = "1.27.1"
+version = "1.27.2"
 description = "SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates."
 authors = ["Fred Visser <fred.visser@emerson.com>"]
 packages = [{ include = "slcli" }]

{systemlink_cli-1.27.1 → systemlink_cli-1.27.2}/slcli/_version.py

@@ -1,4 +1,4 @@
 """Version information for slcli."""
 
 # This file is auto-generated. Do not edit manually.
-__version__ = "1.27.1"
+__version__ = "1.27.2"

systemlink_cli-1.27.2/slcli/skills/slcli/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: slcli
+description: >-
+  Query and manage NI SystemLink resources using the slcli command-line interface.
+  Use when the user asks about test results, assets, systems, work items,
+  specifications, webapps, notebooks, dataframes, files, feeds, tags,
+  authorization, users, example fixture authoring, example config.yaml files,
+  or other SystemLink resource workflows. Use it when the user asks to create,
+  validate, review, install, or troubleshoot a SystemLink example fixture.
+argument-hint: >-
+  Describe the SystemLink workflow you want to inspect, automate, scaffold, or
+  troubleshoot.
+---
+
+# SystemLink CLI
+
+Use this skill when the task is primarily about `slcli` commands or a
+SystemLink resource workflow that should be driven from the CLI.
+
+## When to use it
+
+- Querying or managing SystemLink resources through `slcli`
+- Looking up exact command syntax, flags, or JSON output patterns
+- Building command sequences for analysis, provisioning, packaging, or cleanup
+- Creating, validating, or reviewing `slcli example` fixture YAML
+- Troubleshooting CLI behavior, platform gating, or command selection
+
+## Reference docs
+
+Load only what the current task needs.
+
+| Topic | File | When to load |
+| --- | --- | --- |
+| CLI command reference | [commands.md](./references/commands.md) | Looking up command syntax, options, or examples |
+| Example fixture authoring | [example-authoring.md](./references/example-authoring.md) | Creating or reviewing `config.yaml`, resource references, file-backed fixtures, or validation behavior |
+| Datasheet-to-spec workflow | [datasheet-workflow.md](./references/datasheet-workflow.md) | Importing specifications from PDF, CSV, or structured text |
+| Minimal spec import payload | [import-specs.min.json](./references/import-specs.min.json) | Need a bundled create-compatible starter payload or conditions |
+| Spec import helper | [spec_import_helper.py](./scripts/spec_import_helper.py) | Scaffold or validate a datasheet spec import payload |
+| Filtering guide | [filtering.md](./references/filtering.md) | Advanced filters, LINQ syntax, and query composition |
+| Analysis recipes | [analysis-recipes.md](./references/analysis-recipes.md) | Multi-step analysis workflows and reporting patterns |
+| Troubleshooting | [troubleshooting.md](./references/troubleshooting.md) | SSL, workspace IDs, encoding, or scripting pitfalls |
+| Notebook workflow | [notebook/overview.md](./references/notebook/overview.md) | Creating notebooks for SystemLink |
+| Webapp workflow | [webapp/overview.md](./references/webapp/overview.md) | Hosted Angular webapp scaffolding and deployment |
+| Python test workflow | [python-test/overview.md](./references/python-test/overview.md) | Python test app structure and deployment |
+| Job debugging | [job-debugging/overview.md](./references/job-debugging/overview.md) | Salt job triage and recovery |
+| NI package files | [nipkg/overview.md](./references/nipkg/overview.md) | File-package assembly and `nipkg pack` guidance |
+
+## Default approach
+
+1. Prefer long-form flags in generated commands.
+2. Use `--format json` when the result will be filtered, transformed, or piped
+   into other tools.
+3. Use `--summary --group-by` for aggregation before fetching large raw result sets.
+4. Use convenience filters first, then fall back to `--filter` with `--substitution` for complex queries.
+5. Stay scoped to the user’s requested resource or workflow.
+6. Load deeper references only when the command surface alone is not enough.
+7. For example authoring or review, load `example-authoring.md` before proposing YAML.
+8. Prefer workspace IDs over names in scripted workflows when an endpoint is strict about identity.
+9. Use `make_api_request` from `slcli.utils` for helper scripts so auth, SSL, and error handling stay consistent.
+10. For datasheet imports, default to autonomy when the product or workspace can be resolved unambiguously.
+
+## Common command groups
+
+| Group | Purpose | Key subcommands |
+| --- | --- | --- |
+| `testmonitor` | Test results and products | `result list/get`, `product list/create/update` |
+| `alarm` | Alarm monitoring and lifecycle actions | `list`, `get`, `acknowledge`, `force-clear`, `delete`, `transition`, `monitor` |
+| `spec` | Specifications | `list`, `query`, `get`, `create`, `import`, `export` |
+| `asset` | Assets and calibration | `list`, `get`, `summary`, `calibration` |
+| `system` | System fleet | `list`, `get`, `compare`, `summary`, `job` |
+| `tag` | Tag read/write | `list`, `get-value`, `set-value`, `create` |
+| `routine` | Event-action routines | `list`, `create`, `enable/disable` |
+| `comment` | Resource comments | `list`, `add`, `update`, `delete` |
+| `workitem` | Work items and workflows | `list`, `create`, `schedule`, `template`, `workflow` |
+| `file` | File management | `list`, `upload`, `download`, `query`, `watch` |
+| `notebook` | Jupyter notebooks | `manage list/create`, `execute start/sync` |
+| `feed` | Package feeds | `list`, `create`, `package upload` |
+| `customfield` | Dynamic form fields | `list`, `create`, `export`, `edit` |
+| `template` | Test plan templates | `list`, `import`, `export` |
+| `webapp` | Web applications | `new`, `pack`, `publish`, `list` |
+| `config` | Connection profiles | `list`, `use`, `add`, `delete` |
+| `user` | User management | `list`, `get`, `create`, `update` |
+| `auth` | Authorization policies | `policy list/create`, `template list` |
+| `workspace` | Workspaces | `list`, `get` |
+| `skill` | AI skill installation | `install` |
+| `example` | Demo provisioning | `list`, `install`, `delete` |
+
+Example package fixtures are declared as `package` resources after a `feed`
+resource. Use `source.type: dummy` for deterministic packages, `file` for a
+fixture-relative `.nipkg`, or `repository` for an explicit HTTPS package URL.
+The repository catalog can identify packages and feeds, but package bytes must
+come from a direct package URL or an existing feed download path.
+
+## Mandatory scope resolution
+
+Before the first resource query, resolve the profile and workspace separately.
+Treat a workspace supplied by the user as a workspace identifier, never as a
+profile name. Match it exactly against either the workspace name or UUID.
+
+1. Run `slcli config list --format json` and select profiles whose `workspace`
+  field matches the requested workspace name. If the user supplied a UUID,
+  probe configured profiles sequentially instead. Do not infer a profile from
+  a similar name such as `demo-fred` or `fred-roaster`.
+2. Use the global `--profile NAME` override on every command. The option goes
+  before the command group, for example:
+
+  ```bash
+  slcli --profile PROFILE_NAME workspace list --format json
+  ```
+
+  This preserves the user's global active profile.
+3. If several profiles match, probe them sequentially with
+  `slcli --profile NAME info --skip-health --format json`. Continue past a
+  missing credential, unavailable endpoint, or permission error. Confirm the
+  selected candidate with one read-only workspace query before issuing the
+  actual resource query. Do not fan out the same query across candidates.
+4. Use the first authorized candidate. Ask the user only when several
+  candidates are authorized and the choice could change the answer.
+5. With the selected profile, run `workspace list --format json` and resolve
+  the requested workspace by exact name or UUID. Carry both the display name
+  and UUID, but use the UUID for subsequent queries when the command accepts
+  it.
+
+When reading `slcli info --format json`, use `active_profile_name` as the
+effective profile after CLI or environment overrides. `current_profile` is the
+persisted config pointer and may differ. Use `api_url_source` to confirm where
+the effective endpoint came from; never use `current_profile` alone to decide
+which profile served a query.
+
+## Mandatory non-interactive webapp deployment protocol
+
+For every webapp creation, publish, redeploy, or update task, load
+[deployment.md](./references/webapp/deployment.md) and follow its ordered
+protocol. Do not build or upload an artifact until the deployment target has
+been resolved. The protocol is non-interactive: use JSON output and bounded
+inventory commands, and do not rely on table pagination or terminal prompts.
+
+1. Discover the installed command surface before composing commands:
+  ```bash
+  slcli config list --format json
+  slcli webapp publish -h
+  slcli webapp list -h
+  ```
+  Installed `--help` wins over this skill and its references. Confirm every
+  option on the installed CLI; `webapp publish` currently has `--id`, `--name`,
+  and `--workspace`, while `webapp list` has bounded JSON output and `-f`.
+  Prefer long options in generated commands after confirming they exist.
+2. Resolve the effective profile and target workspace separately. Probe a
+  candidate with `info --skip-health --format json`, resolve the workspace
+  display name to its UUID with `workspace list --format json`, and carry the
+  UUID into every later command. Never use a similar profile name as a
+  substitute for workspace identity.
+3. Resolve the exact webapp target before building or uploading. Use a
+  bounded, filtered, non-interactive inventory, for example:
+  ```bash
+  slcli --profile PROFILE webapp list \
+    --workspace WORKSPACE_ID --filter "Coffee Tasting" \
+    --take 10 --format json
+  ```
+  The server-side `--filter` is a substring filter, so compare returned names
+  locally. One exact name match means update that webapp with its returned ID
+  by default. Multiple exact matches are ambiguous and require a selected ID.
+  No exact match means report that a new resource would be created and obtain
+  explicit confirmation or an explicit create instruction before using
+  `--name`; never create a duplicate as an implicit fallback.
+4. Inspect the project contract before running its dev server or production
+  build. Read `package.json` and `angular.json`; do not append `--host` when
+  the package script already supplies it. Remove or correct legacy Angular
+  options such as `buildOptimizer` and `vendorChunk` when they make `ng serve`
+  reject the configuration. Run the production build, detect its actual
+  output directory, and verify the hosted routing, CSP, authentication, and
+  service/workspace contract. The Test Monitor results service prefix is
+  `/nitest/v2/query-results`, not `/nitestmonitor/v2/query-results`; do not
+  hardcode `workspace=Default` when the target workspace was resolved.
+5. Publish only after steps 1-4 pass. Pass the resolved workspace for a new
+  webapp, or the exact existing webapp ID for an update. Capture the returned
+  webapp ID, published URL, and publish timestamp in the task record.
+6. Validate at three levels: deployment metadata with `webapp get`, an
+  authenticated CLI query for the target workspace and required resources,
+  and an authenticated browser check of the hosted URL. A reachable URL is
+  not proof of an authenticated app. If the browser redirects to login or
+  returns 401, report exactly: `deployment reachable, interactive hosted
+  validation pending.`
+
+## Product lookup and overview defaults
+
+For product discovery, use this order:
+
+1. Try an exact or likely part number with `testmonitor product list
+  --part-number`.
+2. Try the name and family convenience filters.
+3. If a convenience filter returns `[]`, treat that as inconclusive. Scan the
+  resolved workspace catalog with a bounded JSON query and match name or part
+  number locally with `jq`.
+4. Fetch the selected product with `testmonitor product get <PRODUCT_ID>`.
+
+For a product overview, fetch the product record and directly linked metadata
+only. Use `--summary` for counts and statuses, and grouped summaries for
+profiles, programs, or other supported dimensions. For result data, use only
+dimensions exposed by the command, such as `status` and `programName`. Fetch
+only the latest 5 to 10 results, projecting relevant fields with `jq`. Fetch
+full result details only for a specific run or failure. Record an explicit UTC
+`as of` time and treat counts from separate live queries as separate
+observations.

{systemlink_cli-1.27.1 → systemlink_cli-1.27.2}/slcli/skills/slcli/references/analysis-recipes.md

@@ -17,10 +17,94 @@ Each recipe maps to a real-world scenario and shows the exact commands needed.
 - [Recipe 9: Product family workload distribution](#recipe-9-product-family-workload-distribution)
 - [Recipe 10: Environmental condition failure patterns](#recipe-10-environmental-condition-failure-patterns)
 - [Recipe 11: Create and schedule a work item on a specific fixture/slot and system](#recipe-11-create-and-schedule-a-work-item-on-a-specific-fixtureslot-and-system)
+- [Product discovery and overview](#product-discovery-and-overview)
 - [General tips](#general-tips)
 
 ---
 
+## Product discovery and overview
+
+**Question:** Tell me about a product in a specific workspace without
+producing an oversized, inconsistent report.
+
+**Prerequisite:** Complete the mandatory profile and workspace resolution in
+the main `slcli` skill. Set `PROFILE` to the selected profile and
+`WORKSPACE_ID` to the resolved workspace UUID. Capture the observation time
+before querying live data:
+
+```bash
+PROFILE="<PROFILE_NAME>"
+WORKSPACE_ID="<WORKSPACE_UUID>"
+AS_OF="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+printf 'As of %s\n' "$AS_OF"
+```
+
+**Lookup order:**
+
+```bash
+# 1. Exact or likely part number
+slcli --profile "$PROFILE" testmonitor product list \
+  --workspace "$WORKSPACE_ID" --part-number "<PART_NUMBER>" \
+  --format json --take 25
+
+# 2. Name or family convenience filters, when the part-number lookup is empty
+slcli --profile "$PROFILE" testmonitor product list \
+  --workspace "$WORKSPACE_ID" --name "<PRODUCT_NAME>" \
+  --format json --take 25
+slcli --profile "$PROFILE" testmonitor product list \
+  --workspace "$WORKSPACE_ID" --family "<FAMILY>" \
+  --format json --take 25
+
+# 3. Bounded workspace catalog fallback when convenience filters are empty
+slcli --profile "$PROFILE" testmonitor product list \
+  --workspace "$WORKSPACE_ID" --format json --take 100 |
+  jq --arg name "<PRODUCT_NAME>" --arg part "<PART_NUMBER>" '
+    [ .[] | select(
+        (($name != "") and ((.name // "" | ascii_downcase) | contains($name | ascii_downcase)))
+        or (($part != "") and ((.partNumber // "" | ascii_downcase) | contains($part | ascii_downcase)))
+      ) | {id, name, partNumber, family, workspace} ]'
+```
+
+An empty result from a name or family filter does not prove that the product is
+absent. Increase the bounded catalog limit only deliberately, and project the
+candidate fields in `jq` before displaying them. Fetch the selected record only
+after identifying its ID:
+
+```bash
+slcli --profile "$PROFILE" testmonitor product get <PRODUCT_ID> --format json
+```
+
+**Overview budget:**
+
+```bash
+# Directly linked metadata, only when relevant to the question
+slcli --profile "$PROFILE" spec list --product <PRODUCT_ID> --format json
+
+# Compact counts and status breakdown
+slcli --profile "$PROFILE" testmonitor result list \
+  --part-number "<PART_NUMBER>" --summary --group-by status \
+  --format json
+
+# Grouped program summary
+slcli --profile "$PROFILE" testmonitor result list \
+  --part-number "<PART_NUMBER>" --summary --group-by programName \
+  --format json
+
+# Latest 5 to 10 results, projected to relevant fields
+slcli --profile "$PROFILE" testmonitor result list \
+  --part-number "<PART_NUMBER>" --order-by STARTED_AT --descending \
+  --take 10 --format json |
+  jq '[.[] | {id, status: .status.statusType, startedAt, programName,
+               partNumber, serialNumber}]'
+```
+
+Use `testmonitor result get <RESULT_ID> --include-steps --format json` only
+when the user asks about a particular run or failure. Counts from separate
+commands are not one atomic snapshot; report the `as of` time and call out
+live-data changes when totals do not agree.
+
+---
+
 ## Recipe 1: Operator failure rate analysis
 
 **Question:** Which operators have the highest failure rates and what should they
@@ -482,8 +566,9 @@ slcli workitem schedule wi-12345 \
 - **Start with `--summary`** to understand data shape before fetching raw records.
 - **Use `--group-by`** with `--summary` for aggregation: `status`, `programName`,
   `serialNumber`, `operator`, `hostName`, `systemId`.
-- **Chain with `jq`** for complex transformations — always use `-f json`.
-- **Use `--take` wisely** — start small (100-500), increase if needed.
+- **Chain with `jq`** for complex transformations — always use `--format json`.
+- **Use `--take` wisely** — start with 5-10 for recent detail and a bounded
+  catalog query for discovery; increase only when the question requires it.
 - **For rate calculations**, query total count and filtered count separately, then divide.
 - **Use `--order-by TOTAL_TIME_IN_SECONDS --descending`** to find slowest tests quickly.
 - **Asset `--connected` flag** limits to assets in currently connected systems.

{systemlink_cli-1.27.1 → systemlink_cli-1.27.2}/slcli/skills/slcli/references/commands.md

@@ -28,6 +28,31 @@ Complete option reference for all `slcli` command groups.
 - [webapp — Web application management](#webapp--web-application-management)
 - [skill — AI skill installation](#skill--ai-skill-installation)
 - [example — Built-in example resource provisioning](#example--built-in-example-resource-provisioning)
+- [Scope and capability discovery](#scope-and-capability-discovery)
+
+## Scope and capability discovery
+
+Resolve a requested workspace before querying its resources. `--profile` is a
+global option and must precede the command group:
+
+```bash
+# Find profiles mapped to the requested workspace
+slcli config list --format json | \
+  jq -r --arg workspace "Fred" '.[] | select((.workspace // "") == $workspace) | .name'
+
+# Probe candidates one at a time without changing the active profile
+slcli --profile <PROFILE_NAME> info --skip-health --format json
+slcli --profile <PROFILE_NAME> workspace list --format json
+```
+
+In `info` JSON, `active_profile_name` is the effective profile for the command,
+while `current_profile` is the persisted config pointer. `api_url_source`
+identifies the source of the effective API URL. Use the effective fields when
+they disagree; `current_profile` alone is not a reliable query-scope signal.
+
+Consult `<command> --help` whenever a flag or alias is uncertain. Format aliases
+are command-specific, and the installed CLI help is authoritative. Generated
+commands should prefer the long form `--format json`.
 
 ## testmonitor — Test data analysis
 
@@ -78,7 +103,7 @@ slcli testmonitor product list [OPTIONS]
   --workspace, -w TEXT       # Filter by workspace name or ID
   --summary                  # Show summary statistics
   --take, -t INTEGER         # Items per page (default 25)
-  -f [table|json]
+  --format, -f [table|json]
 
 # Get a single product
 slcli testmonitor product get <PRODUCT_ID> [-f json]
@@ -665,8 +690,8 @@ slcli comment delete <ID1> <ID2> <ID3>
 ## workspace — Workspace management
 
 ```bash
-slcli workspace list [-f json]
-slcli workspace get --workspace WORKSPACE_ID [-f json]
+slcli workspace list [--format json]
+slcli workspace get --workspace WORKSPACE_ID [--format json]
 slcli workspace disable --id WORKSPACE_ID [--yes]
 ```
 
@@ -681,7 +706,7 @@ slcli logout [--profile NAME] [--all] [--force]
 slcli info [-f json] [--skip-health]            # Show active profile and service health
 slcli completion [--shell SHELL] [--install]    # Generate or install shell tab completion
 
-slcli config list [-f json]                     # List all profiles
+slcli config list [--format json]               # List all profiles
 slcli config current                            # Show the active profile name
 slcli config use <PROFILE>                      # Switch the active profile
 slcli config view [-f json] [--show-secrets]    # Show stored profile details
@@ -896,13 +921,20 @@ is intentionally omitted from the recommended command sequence.
 slcli webapp new <APP_NAME> [OPTIONS]                # Generate a hosted Angular webapp
 slcli webapp manifest init <DIRECTORY> [OPTIONS]  # Create nipkg.config.json for packaging
 slcli webapp pack [FOLDER] [--config FILE] [--output OUTPUT_FILE]  # Package a webapp into a .nipkg
-slcli webapp list [-w WORKSPACE] [--filter TEXT] [--take INT] [--format json]
+slcli webapp list [-w WORKSPACE] [--filter TEXT] [--take INT] [--format FORMAT] [-f FORMAT]
 slcli webapp get --id WEBAPP_ID [--format json]
-slcli webapp publish PATH [--workspace NAME]             # Upload and publish a webapp
+slcli webapp publish PATH --id WEBAPP_ID                # Update an existing webapp
+slcli webapp publish PATH --name NAME --workspace NAME  # Create metadata and upload
 slcli webapp delete --id WEBAPP_ID [--yes]
 slcli webapp open --id WEBAPP_ID                          # Open webapp URL in browser
 ```
 
+`webapp list` supports both `--format` and `-f` in the current CLI. Older
+installed versions may expose only the long form, so use `slcli webapp list
+--help` to verify the local command surface before scripting against it.
+`webapp publish` has no output-format option; use `webapp get --format json`
+after publishing when structured deployment metadata is needed.
+
 For an existing Angular project, work in that project directly and load the
 webapp references as needed. Do not introduce the legacy `webapp init` step
 into a new project workflow.

{systemlink_cli-1.27.1 → systemlink_cli-1.27.2}/slcli/skills/slcli/references/troubleshooting.md

@@ -2,6 +2,25 @@
 
 Common issues and workarounds when using `slcli` or scripting against SystemLink APIs.
 
+## Effective profile and workspace scope
+
+Resolve the workspace and profile independently before querying resources. A
+workspace name is not a profile name. Use `slcli config list --format json` to
+find profiles mapped to the workspace, then pass the selected profile before
+each command with `slcli --profile NAME ...`.
+
+When `slcli info --format json` shows different values, use
+`active_profile_name` for the effective profile and `api_url_source` for the
+effective endpoint. `current_profile` is only the persisted config pointer and
+may be stale relative to a CLI or environment override.
+
+## Live-data snapshots
+
+Queries are live and may change between commands. Record the query time and
+avoid presenting counts from separate commands as one atomic snapshot. If
+multiple aggregations must agree exactly, fetch one bounded JSON result set and
+derive all aggregations locally.
+
 ## Workspace IDs vs names
 
 Some API endpoints (notably **file upload**) require the workspace **UUID**, not