输出格式

UiPath CLI 中的输出格式，涵盖每个命令发出的结构化信封，采用 JSON、表格、YAML 和纯渲染格式。

Every uip command emits a single structured envelope on stdout. The envelope has the same schema whether you are reading it in a terminal, feeding it into jq, or consuming it from a pipeline. Five formats render that envelope differently: json (the default), table, yaml, plain, and markdown. Switch between them with --output and filter with --output-filter.

信封

成功：

{
  "Result": "Success",
  "Code": "FolderList",
  "Data": [
    {
      "Key": "9f2b3c…-…",
      "Name": "Shared",
      "Path": "Shared",
      "Type": "Standard"
    }
  ]
}

失败：

{
  "Result": "ValidationError",
  "Message": "Unknown option '--folder-pth'. Did you mean '--folder-path'?",
  "Instructions": "Run 'uip or folders list --help' to see valid options.",
  "ErrorCode": "invalid_argument",
  "Retry": "RetryWillNotFix",
  "Log": "/var/log/uip/2026-04-24.log"
}

字段：

• Result — 结果类别。成功时，为Success ；失败时为Failure 、 ConfigError 、 AuthenticationError 、 ValidationError或TimeoutError 。直接映射到退出代码。
• Code — 特定于命令的成功标识符。在主要版本（ FolderList 、 SolutionPack 、 JobStarted 、 SkillsInstall等）中保持稳定。
• Data — 命令的有效负载。形状是特定于命令的；有关确切字段，请参阅每个命令的参考页面。
• Message 、 Instructions — 失败时显示。Message是人类可读的错误； Instructions告诉用户或操作员要执行的操作。
• ErrorCode — present on every failure. A stable, command-independent taxonomy for scripts that need finer-grained branching than the exit code alone: invalid_argument, authentication_required, permission_denied, local_permission_denied, not_found, rate_limited, network_error, timeout, server_error, method_not_allowed, configuration_error, unknown_error.
• Retry — present on every failure. Whether retrying is worth it, and how soon: RetryWillNotFix, RetryLater, RetryAfter1Second, RetryAfter10Seconds, RetryAfter30Seconds, RetryAfter60Seconds.
• Context — 可选的失败详细信息（HTTP 状态、请求 ID 等）。
• Log — 当--log-file处于活动状态时，表示日志文件的路径，包含在每个信封中。

ErrorCode and Retry are populated automatically on every failure, even when a command doesn't set them explicitly — see Scripting patterns — retrying on Retry for how to branch on them instead of parsing Message text.

信封本身在次要版本中保持稳定。Data的形状视命令而定，并且可以不断发展 — 请参阅版本控制和稳定性。

The five formats

JSON（默认）

uip or folders list

{
  "Result": "Success",
  "Code": "FolderList",
  "Data": [
    { "Key": "9f2b3c…", "Name": "Shared", "Path": "Shared", "Type": "Standard" },
    { "Key": "a4b8f1…", "Name": "Finance", "Path": "Finance", "Type": "Standard" }
  ]
}

选择默认值是因为它可由任何 JSON 使用者（ jq 、 --output-filter 、脚本、AI 智能体）解析，并且在各个版本中具有确定性。在终端中，其读取效果良好；如需获得打印美观的表格，请切换到--output table 。

表格

uip or folders list --output table

Key         Name       Path      Type
9f2b3c…     Shared     Shared    Standard
a4b8f1…     Finance    Finance   Standard

在真实终端中设置颜色和边框（当标准输出不是 TTY 时，不显示颜色）。每个命令都会选取它认为对表格视图最有用的列，但不一定显示Data中的每个字段。对于完整的字段集，请使用 JSON 或 YAML。

不解析表格输出。列宽、边框甚至列集都可能在 Minor 版本之间发生变化。它仅供人类阅读。

YAML

uip or folders list --output yaml

Result: Success
Code: FolderList
Data:
  - Key: 9f2b3c…
    Name: Shared
    Path: Shared
    Type: Standard
  - Key: a4b8f1…
    Name: Finance
    Path: Finance
    Type: Standard

与json相同的信封的文本 YAML 序列化。如果您的工具更喜欢 YAML（Ansible、Kubernetes 清单、某些 CI 平台），或者您通过目视比较两次运行并发现 YAML 更容易扫描，则此方法非常有用。

plain

uip or folders list --output plain

Data[0].Key=9f2b3c…
Data[0].Name=Shared
Data[0].Path=Shared
Data[0].Type=Standard
Data[1].Key=a4b8f1…
Data[1].Name=Finance
Data[1].Path=Finance
Data[1].Type=Standard

每行一个path=value 。路径是信封中点符号的类似 JMES 路径的密钥。可方便用于没有jq的计算机上的 Shell 循环：

uip or folders list --output plain | grep -E '\.Name=' | cut -d= -f2

markdown

uip or folders list --output markdown

| Key | Name | Path | Type |
| --- | --- | --- | --- |
| 9f2b3c… | Shared | Shared | Standard |
| a4b8f1… | Finance | Finance | Standard |

Renders the envelope as GitHub-flavored markdown — a table for a list of records, or **key:** value lines and nested headed sections for a single record. Intended for an agent or chat surface reading uip output through a shell, not for a human terminal session: a command that already returns prose (for example uip rpa validate) passes it through verbatim instead of as an escaped JSON string. On failure, the format renders **Failed:** <Message> followed by any Data and Instructions.

使用 --output-filter 进行筛选

--output-filter接受JMESPath表达式。系统会在格式化之前在完整信封上运行，因此筛选器输出会继承--output生成的格式。

一些常见模式：

# just the Data array
uip or folders list --output-filter "Data"

# project specific fields
uip or folders list --output-filter "Data[*].{name: Name, path: Path}"

# count
uip or folders list --output-filter "length(Data)"

# first match
uip or folders list --all --name Shared --output-filter "Data[0]"

# flat list of names
uip or folders list --output-filter "Data[*].Name" --output plain

在命令运行之前，格式错误的表达式会以ValidationError退出（退出代码3 ），因此即使输入错误也不会浪费一次 API 调用。请参阅全局选项 — --output-filter ，了解完整标记。

流分离

--output仅控制标准输出。无论格式如何，所有其他形式的输出都将发送到STDERR ：

• 日志行（ --log-level控制的内容）。
• 进度指示器（微调框、工具自动安装期间的下载栏）。
• 主机在检测到无效标志时呈现的错误文本。

这意味着管道可以将干净输出捕获到文件中，而不会丢失诊断信息：

uip or folders list > folders.json 2> uip.log

在 CI 中，单独对其进行重定向，以使日志可搜索，而无需从数据流中去除 ANSI 或进度工件。

颜色和 TTY 检测

The table format emits ANSI color codes when stdout is an interactive terminal (isTTY). When you pipe to a file or to another process, or run in a CI runner that disables TTY, table output is plain text without escape codes by default.

Two environment variables override TTY auto-detection:

变量	效果
NO_COLOR	Any value forces color off, even on a TTY.
FORCE_COLOR	Forces color on, even when stdout is not a TTY — useful when a CI log viewer renders ANSI codes and you want the colored table anyway.

其他格式（ json 、 yaml 、 plain ）从不发出颜色。

Overriding the default format

--output defaults to json when omitted. Set UIP_DEFAULT_OUTPUT to change that default for the current shell without passing --output on every command:

export UIP_DEFAULT_OUTPUT=table
uip tools list                  # → table

uip tools list --output yaml   # --output still wins → yaml

Accepts table, json, yaml, plain, or markdown; an invalid value is ignored and the built-in json default is kept.

选择格式

Use case	建议的格式
在终端中读取	--output table
脚本编写（ jq 、Shell 管道）	--output json (默认)
Ansible/Kubernetes 集成	--output yaml
grep- 友好的平面输出，不包含 jq	--output plain
AI 编码智能体	--output json (default) with --output-filter for focused extraction, or --output markdown for a chat-readable rendering
在步骤之间传递值的 CI 管道	--output json 带有--output-filter或--output plain （对于简单情况）

另请参阅

• 全局选项— --output 、 --output-filter 、 --log-level和--log-file标志。
• 退出代码— 从Result映射到流程退出代码。
• 脚本模式— CI 中的重试、轮询和安全 JSON 提取。
• 版本控制和稳定性— 在 semver 中，“稳定的 JSON 信封”意味着什么。