curl · curl project
curl Agent 使用指南
通过显式方法、请求头、认证、重试和失败处理调用 HTTP API。
官方工具操作风险: R0–R3verified
为 Agent 安装
选择与运行环境匹配的官方安装方式。在团队或 CI 环境中固定版本，并先运行版本检查。
用于稳定自动化的结构化输出
优先使用机器可读格式，并把 stdout 作为结果、stderr 作为诊断信息分别处理。
R0–R3 命令风险指南
风险按单条命令判断。R0 是本地或远程只读，R1 是可逆的本地写入，R2 会改变远程状态，R3 可能造成不可逆或生产级影响。
只读不等于可公开
R0 只表示命令不更改本地或远程状态。只读命令仍可能返回令牌、身份信息、配置或生产数据；只展示完成任务所需的最少内容，不得写入日志、Prompt 或提交内容。
Agent Readiness 评分依据
适配度描述 Agent 操作工具的稳定程度，不代表所有命令都安全，也不替代独立执行测试。
文档证据对应的 Agent Readiness 为 84/100；已记录 8.7.1 的有限本地 Smoke Test，使用未测试命令前仍需查看证据边界。
生成 Skill 或 Agent 策略
选择目标 Agent 和安全模式，生成包含安装、允许命令、确认边界与证据说明的可复制产物。
生成结果预览
SKILL.md
---
name: curl-agent-workflow
description: Use curl for HTTP APIs, file transfers, health checks with explicit command risk and evidence boundaries.
---
# curl agent workflow
Use this skill when the task needs HTTP APIs, file transfers, health checks, webhook calls.
## Evidence boundary
- Registry confidence: `verified`
- Documentation checked: `2026-07-10`
- Locally tested version: `8.7.1`
- Treat only the recorded executed checks as independently verified; every unlisted command remains documentation-only.
## Executed smoke checks
- `curl --version` — passed; exit 0. The recorded smoke check completed successfully.
- `curl --fail --silent --show-error --max-time 5 file://$PWD/package.json` — passed; exit 0. The recorded smoke check completed successfully.
- `curl --fail --silent --show-error --max-time 5 file://$PWD/package.json | jq -e '.name == "clifinder-net"'` — passed; exit 0. The bounded local file response passed the recorded jq assertion.
- `curl --fail --silent --show-error --max-time 5 file://$PWD/not-a-real-qa-file` — expected-failure; exit 37. curl returned its documented local-file open error and kept the diagnostic on stderr.
## Installation
- Homebrew (macos, linux): `brew install curl`
- winget (windows): `winget install cURL.cURL`
## Authentication
- Methods: none, basic, bearer token, client certificate, netrc
- Secret environment variables: `HTTP_TOKEN`
- Minimum permissions: Pass scoped tokens through environment-backed headers and never print request secrets.
- Credential storage: For headless runs, inject HTTP_TOKEN from the CI or platform secret manager at process start. For local interactive use, prefer the CLI or operating-system credential store when the official client supports one. Never save values in repository files.
- Never print, persist, or commit credential values.
## Allowed commands (read-only)
- `curl --fail-with-body --silent --show-error --header "Accept: application/json" https://api.example.com/items` — R0: Performs a failing-fast GET request and preserves the response body.
## Commands requiring explicit approval (read-only)
- None recorded.
## Forbidden commands (read-only)
- R2 `curl --fail-with-body --request POST --header "Content-Type: application/json" --data @payload.json https://api.example.com/items` — Sends a state-changing POST request.
- R3 `curl --fail-with-body --request DELETE https://api.example.com/items/ID` — Sends a potentially destructive DELETE request.
## Execution rules
1. Mode boundary: R0 exact commands may be used; R1, R2, and R3 commands are forbidden.
2. Confirm the selected account, project, context, database, namespace, or environment before any command.
3. Prefer structured output using `--fail-with-body`, `--silent`, `--show-error`.
4. Capture the exact command, exit code, stdout, and stderr separately.
5. A generated prefix policy must prompt unless that exact prefix is explicitly marked suffix-safe; do not infer safety from the executable name.
6. Never broaden credentials or disable safety controls to make a command succeed.
## Official sources
- [curl manual](https://curl.se/docs/manpage.html)
- [curl manual source repository](https://github.com/curl/curl)
验证记录与官方证据
CLI Finder 分开记录文档检查和真实执行。未执行过的安装、帮助、退出码与输出不能标为 Verified。