# CLI Conventions (authoring)

This reference covers the **authoring-side** CLI surface only: the read-only
registry discovery commands used to produce a valid, importable Maestro `.bpmn`
file. The registry commands below never mutate cloud state. Operate and diagnose
use different CLI commands — see
[operate/CAPABILITY.md](operate/CAPABILITY.md) and
[diagnose/CAPABILITY.md](diagnose/CAPABILITY.md).

## Discovery commands (read-only, authoring-safe)

All commands below are discovery/read-only. None mutate cloud state.

| Command | Purpose |
| --- | --- |
| `uip maestro bpmn registry pull [-f\|--force]` | Sync and cache the registry. Without login, only OOTB extension types are synced; login adds discovered connectors and processes. |
| `uip maestro bpmn registry list [--limit <n\|-1>]` | List cached extension types (and discovered connectors/processes). Default 30; use `--limit -1` for all. |
| `uip maestro bpmn registry search <keyword>` | Find entries by keyword across extension type, label, connector name, process name. |
| `uip maestro bpmn registry get <extensionType> [--connection-id <id>] [--object-name <name>]` | Get the full spec for one extension type: `xmlTemplate`, `contextFields`, `bindingInfo`, input/output patterns. `--connection-id`/`--object-name` add live Integration Service field metadata for `Intsvc.*` connector types. |
| `uip is connections list --all-folders` | List live Integration Service connections (id + state) across all folders. Always pass `--all-folders`; a folder-scoped list silently misses connections. |
| `uip rules list --all-folders` | List deployed business rules across all folders. `registry pull` does not discover rules. |

These are the registry/discovery commands the skill verifies against the CLI
source (`packages/maestro-tool/src/commands/registry.ts`). Do not invent flags.
Validation uses `uip maestro bpmn validate <file>` — see
[Validation](structural-bpmn.md#validation).

The `validate` command runs the full PO.Frontend canvas rule set offline (it was
added to the CLI in UiPath/cli#3135). If your CLI reports `validate` as an
unknown command, or it clearly runs only the deploy-readiness checks and not the
structural rules, the installed CLI predates that change — update to the latest:

```bash
npm install -g @uipath/cli@latest   # or: bun add -g @uipath/cli
```

An exit-0 validation result is structural preflight only. It does not execute
the BPMN engine and cannot establish that public input/output bridges or
business outputs produce the intended runtime values. Do not describe `Valid`
as a successful business execution.

> **Don't conclude "it doesn't exist" from truncated discovery output.** A row past a cutoff reads exactly like a missing row. Two cutoffs bite here: `registry list` defaults to **30** — pass `--limit -1` for the full set — and piping `registry search`/`is connections list` through `head`/`tail`/`sed -n`/`grep -m`/a pager drops everything past the cap. To check existence, narrow the query (keyword to `registry search`, `--all-folders` to connection lists) rather than capping rows; cap only data already known complete.

## Output parsing

Whenever a CLI result is parsed programmatically, pass `--output json`, and
redirect stdout only; stderr carries stack traces, so `2>&1` produces a file
no JSON parser accepts. If a command does not support JSON, do not silently
scrape human text; keep the step manual and tell the user.

Every command returns one envelope. Envelope keys are fixed; match keys inside
`Data` case-insensitively.

| Key | Present | Use |
| --- | --- | --- |
| `Result` | always | `Success`, or `Failure` / `ConfigError` / `AuthenticationError` / `ValidationError` / `TimeoutError` |
| `Code` | success; some failures | command tag (`RegistryPullSuccess`, `BpmnRefreshFailed`) |
| `Data` | success | payload; shapes below |
| `Message`, `Instructions` | failure | `Instructions` holds the actionable detail, including the validator's issue list |
| `ErrorCode`, `Retry` | failure | `Retry: RetryWillNotFix` means fix the input; re-running unchanged fails again |
| `Warning` | `uip is` reads | rows returned that cannot be used, e.g. connections not `Enabled` |

Exit codes: `0` Success, `1` Failure/ConfigError, `2` AuthenticationError,
`3` ValidationError, `4` TimeoutError.

`Data` by command:

| Command | `Data` |
| --- | --- |
| `registry pull` | `ExtensionTypeCount`, `ConnectorCount`, `ProcessCount`, `ProcessCountsByType`, `FromCache`, `CacheWritten`, `Message` |
| `registry list`, `registry search` | `ExtensionTypes[]`, `Connectors[]`, `Processes[]`, `ProcessesByType` |
| `registry get` | `ExtensionType` (fields in [registry-workflow.md](registry-workflow.md#2-get-the-template-for-each-chosen-type)); with `--connection-id`/`--object-name`, also a sibling `IsEnrichment` |
| `is connections list` | array of `Id`, `Name`, `ConnectorKey`, `ConnectorName`, `State`, `Owner`, `IsDefault`, `ByoaConnection`, `ElementInstanceId`, `Folder`, `FolderKey`, `Created`, `Updated` |
| `is resources list` | array of `Name`, `DisplayName`, `Path`, `Type`, `SubType`, `Custom`, `Operations`, `ElementKey` |
| `is resources describe` | `Name`, `DisplayName`, `ElementKey`, `Operation`, `Parameters[]`, `RequestFields[]`, `ResponseFields[]`, `Method`. `Method` is a JSON **string**; parse it a second time |
| `validate` | pass: `File`, `Status`, `ProcessCount`, `StartEventCount`, `UiPathExtensionCount`, `Warnings` (one string). Fail: no `Data`; every issue is in `Instructions` |

## Login boundary

Local source authoring and `uip maestro bpmn validate` work without login (the
validator runs fully offline). Registry
discovery of **connectors and processes** (and Integration Service field
enrichment) requires `uip login`. Without login, `registry pull` still returns
the built-in (OOTB) extension types.

## Never fabricate an identifier

Connection IDs, `releaseKey`/process keys, queue keys, connector keys, app IDs,
folder IDs/paths — every concrete identifier comes from discovery
(`registry get`, `registry search`, `uip is connections list`) or from the user.
Never invent one. When a required identifier is unknown, leave the placeholder
in place and flag it as a draft binding (SKILL.md step 1); ask only under
Rule 4.