Using the Uploadcare CLI withย AI coding agents (Cursor, Claude Code, GitHub Copilot, and Codex)
Trust Jamin OkpukoroThe Uploadcare CLI works well withย AI coding agents for agentic file and media workflows: itโs aย single binary anย agent invokes asย aย subprocess, with aย built-in command that describes its full surface soย the agent knows exactly which commands, flags, and fields are available.
In this guide, youโll learn how to connect it to four agents so they can upload files, convert media, and return CDN URLs on their own.
How the Uploadcare CLI works withย AI agents
The Uploadcare CLI was built toย run non-interactively byย outputing structured JSON, returning deterministic exit codes, and exposing its full command surface onย demand. Itย has four properties that make itย ideal forย AI integration.
Self-describing surface. The command uploadcare api-schema provides aย comprehensive, machine-readable JSON schema ofย the entire CLI.
The schema includes all command paths, flags, arguments, and the JSON fields that each command can return, along with agent-specific usage guidance.
Your agent utilizes this schema toย generate valid commands, eliminating the need toย guess method names orย scrape --help text.
Machine-readable output. All commands support --json for machine-readable output, allowing for structured output,
either for all fields orย aย selected subset. Additionally, the --jq option enables filtering withย a jq expression inline.
This provides the agent with aย clean data for reasoning, instead ofย aย table that requires parsing.
Deterministic exit codes. The CLI uses specific exit codes toย indicate the outcome ofย operations.
0for success,1for anย API error,2for aย usage error, and3for anย authentication orย configuration issue.
This allows anย agent orย aย Continuous Integration (CI) job toย make decisions based onย the exit code without needing toย check the accompanying message.
Safe byย default for writes. Destructive commands include a --dry-run flag that allows users toย preview the effects before making any changes.
Soย anย agent can plan aย delete orย migration and show you the result before anything happens.
Since itย isย aย single binary with noย runtime dependencies, there isย noย SDK toย import and noย plugins toย keep synchronized with the platform.
The agent interacts with uploadcare inย the same way itย would with git or curl.
Prerequisites
Toย follow along with this tutorial, youโll need the following:
- Aย free Uploadcare account and your projectโs public and secret API keys
- One ofย the supported agents: Cursor, Claude Code, GitHub Copilot, orย OpenAI Codex
- Aย terminal onย Linux, macOS, orย Windows
- Basic familiarity with your agentโs terminal orย command-approval settings
Install and authenticate the CLI
Every agent below invokes the same binary, soย install itย once. Onย Linux orย macOS, run:
curl -fsSL https://raw.githubusercontent.com/uploadcare/uploadcare-cli/main/scripts/install.sh | shPre-built binaries for Windows and specific versions are onย the GitHub Releases page. Confirm the install worked:
uploadcare --versionNext, authenticate byย exporting your API keys, which youโll find inย your Uploadcare dashboard:
export UPLOADCARE_PUBLIC_KEY="your-public-key"
export UPLOADCARE_SECRET_KEY="your-secret-key"Ifย youโd rather not export the keys every session, the CLI also reads them from aย config file at ~/.uploadcare/config.yaml. When keys are set inย more than one place, the CLI picks them inย this order:
- Command-line flags (highest priority)
- Environment variables
- The config file (lowest priority)
Soย aย value passed asย aย flag wins over anย environment variable, which inย turn wins over the config file. This order isย what lets anย agent orย CI system inject secrets atย runtime: those keys take priority automatically, and your local config file stays untouched.
Note: Keep your secret key out ofย any file the agent commits. Export itย inย the shell the agent inherits, orย store itย inย your agentโs secret manager, rather than writing itย into anย instruction file that lands inย version control.
How agents discover commands with api-schema
Before wiring upย any agent, run this yourself toย see what the agent will see:
uploadcare api-schema | jq -r '.commands[].path'That prints every command path the CLIย exposes: file upload, file list, convert video, and soย on.
Toย inspect aย single commandโs returnable fields:
uploadcare api-schema | jq '.commands[] | select(.path == "file info") | .json_fields'
Terminal output ofย the uploadcare api-schema command listing available command paths asย JSONThis isย the mechanism every integration will relyย on.
Instead ofย hardcoding command syntax into aย prompt (which goes stale the moment the CLIย changes),
you tell the agent toย run uploadcare api-schema and read the result.
The schema isย the single source ofย truth, soย the agent stays correct across CLIย updates.
Using the Uploadcare CLI with Cursor
Cursorโs Agent can run terminal commands, and itย reads rule files from your project root. The setup isย two parts: aย rule that tells the agent when and how toย use the CLI, and aย terminal permission soย itย can actually run the binary.
First, create an AGENTS.md file inย your project root. Cursor reads AGENTS.md (and .cursor/rules) asย agent instructions:
# File uploads and media
This project uses the Uploadcare CLI for all file upload, conversion, and
media tasks. Do not write custom upload code or import an SDK.
- Discover available commands by running `uploadcare api-schema` and reading
the JSON output (command paths, flags, and `json_fields`).
- Prefer `--json` output so you can parse results.
- Preview any destructive command (for example `file delete`) with `--dry-run`
before running it for real.
- API keys are already set as `UPLOADCARE_PUBLIC_KEY` and
`UPLOADCARE_SECRET_KEY` environment variables.The rule above does the following:
- Scopes the tool: itย tells the agent toย reach for the CLIย on any file orย media task, instead ofย hand-rolling anย upload.
- Points at
api-schema: the agent discovers commands itself rather than relying onย syntax baked into the prompt. - Sets aย safety rule: itย requires
--dry-runonย destructive operations, soย the agent plans before itย deletes.
Next, allow the agent toย run the command.
Open Cursorโs Agent settings (Cmd/Ctrl + Shift + J โ Agents โ Auto-Run) and add uploadcare toย the allowlist ofย commands
the agent can run without asking each time. Keep destructive shell commands out ofย the allowlist soย writes still prompt you.
Tip: Start with Auto-Run set toย โAsk Every Timeโ while you watch what the agent does.
Once you trust the flow, move read-only uploadcare commands toย the allowlist and leave deletes onย manual approval.
Now prompt the agent inย natural language, such asย โUpload hero.jpg toย Uploadcare and give meย the CDN URLโ,
and itย will run uploadcare api-schema, find file upload, and executeย it.
Using the Uploadcare CLI with Claude Code
Claude Code running the Uploadcare CLIClaude Code runs Bash commands directly and reads a CLAUDE.md file for project context, soย the pattern mirrors Cursorโs. Add a CLAUDE.md (orย reuse the same AGENTS.md, which Claude Code also reads) toย your project root with the same instructions:
# File uploads and media
Use the Uploadcare CLI for all file upload, conversion, and media operations.
Run `uploadcare api-schema` to discover commands, flags, and JSON fields.
Use `--json` for structured output and `--dry-run` before any delete.Then let Claude Code run the binary without prompting onย every call byย adding aย permission rule to .claude/settings.json inย your project:
{
"permissions": {
"allow": ["Bash(uploadcare:*)"]
}
}Hereโs what that configuration does:
-
Bash(uploadcare:*)allows any command that starts withuploadcare(uploadcare file upload,uploadcare convert video, and the rest), using Claude Codeโs prefix-matching permission syntax. -
Everything else stays gated: because the rule only matches the
uploadcareprefix, other shell commands still follow your default approval mode.
Ifย youโd rather keep deletes behind aย confirmation,
allow the read and write commands you trust and leave uploadcare file delete off the allowlist soย itย prompts.
With that inย place, ask Claude Code toย handle aย file task and itย discovers the command surface through api-schema,
then runs the right command asย aย Bash subprocess.
Using the Uploadcare CLI with GitHub Copilot
GitHub Copilotโs agent mode also runs terminal commands and supports custom instructions. Copilot reads AGENTS.md asย well as .github/copilot-instructions.md, soย you can reuse the instructions from the Cursor section orย add aย Copilot-specific file.
Create .github/copilot-instructions.md:
# File handling
For any file upload, conversion, or media task, use the Uploadcare CLI
(`uploadcare`). Run `uploadcare api-schema` to discover the available commands
and their JSON fields before composing a command. Always request `--json`
output, and preview destructive commands with `--dry-run`.Copilotโs agent will run uploadcare inย the integrated terminal.
Onย Copilot Business orย Enterprise, terminal commands are governed byย anย allow/block policy,
soย confirm that uploadcare isnโt caught byย aย broad blocklist rule (the defaults target commands like rm -rf, sudo, and curlย | sh, not uploadcare).
Ifย your organization uses aย strict allowlist, add uploadcare toย it.
Using the Uploadcare CLI with OpenAI Codex
OpenAI Codex running the Uploadcare CLIOpenAIโs Codex CLI reads an AGENTS.md file for project instructions, the same file Cursor and Copilot use, soย you can reuse the instructions from the earlier sections without writing aย new one.
Codex runs shell commands inside aย sandbox whose autonomy you control with anย approval policy. Set your defaults in ~/.codex/config.toml:
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = trueHereโs what that configuration does:
-
approval_policy = "on-request"lets Codex run the commands itย judges safe and pause for your approval onย the rest, soย reads flow while writes get aย checkpoint. -
sandbox_mode = "workspace-write"confines file writes toย your project directory while still letting theuploadcarebinary run. -
network_access = trueisย the setting toย watch: the CLI calls the Uploadcare API over the network, and Codexโs sandbox blocks network access byย default. Leave itย off anduploadcare file uploadfails with aย connection error rather than anย approval prompt.
With the sandbox allowed toย reach the network, Codex discovers the command surface through api-schema and runs the workflow the same way the other agentsย do.
Note: The four agents share the same two-part pattern: anย instruction file that points at api-schema,
and permission toย run the uploadcare binary. Write the instructions once in AGENTS.md and all four can readย it.
End-to-end examples: two prompts you can hand your agent
Once the instruction file and terminal permission from the sections above are inย place, you donโt spell out the commands yourself.
You describe the goal, and the agent discovers the exact syntax through api-schema.
Here are two realistic tasks, each with the commands the agent runs and a prompt you can paste into any of the four agents.
Exampleย 1: Upload aย product image folder
Uploading aย whole folder isย one command, because the shell expands aย glob and the CLI accepts every matched file:
uploadcare file upload ./products/*.jpg --json allThe --json all flag returns one JSON object per file asย NDJSON (newline-delimited JSON), one per line,
soย the agent reads back every result without parsing aย table.
Toย get each fileโs CDN URL, the agent reads the delivery-URL field the CLIย reports, confirming the exact field name through api-schema,
rather than building aย URL byย hand. That keeps the URLs correct for your account, whose delivery domain the CLI already knows.
Hereโs the prompt:
Upload every image in the ./products folder to Uploadcare, then give me
a list mapping each original filename to its CDN URL.
Use the Uploadcare CLI for the upload and use the `--json` output so you can parse the results.
Steps:
1. Upload all images in ./products folder
2. Read each uploaded file's CDN URL from the JSON output. Don't hardcode a
CDN domain; use the delivery URL the CLI reports.
3. Return a table mapping each original filename to its CDN URL.
If any command exits non-zero, stop and tell me the exit code and what it
means instead of retrying blindly. Do not delete anything.Exampleย 2: Convert aย document toย PDF with aย thumbnail
Document conversion runs asย anย asynchronous job: the agent submits the source fileโs UUID and aย target format, and Uploadcare produces aย new file with its own UUID. The upload and conversion are two commands:
uploadcare file upload contract.docx --json uuid
uploadcare convert document <uuid> --target-format pdfFor the thumbnail, Uploadcare renders aย single document page asย anย image.
Onย the delivery side, thatโs the fileโs CDN URL with the document-conversion operations appended (.../<uuid>/document/-/format/jpg/-/page/1/),
which returns page 1ย as aย JPG. The agent confirms the exact CLI flags for the target format and page selection through api-schema rather than assuming them.
Hereโs the prompt:
Upload ./contract.docx to Uploadcare, convert it to a PDF, and also generate a
thumbnail image of the document's first page. Give me the CDN URL for both the
PDF and the thumbnail.
Use the Uploadcare CLI for the upload and use the `--json` output so you can parse the results.
Steps:
1. Upload ./contract.docx and capture its UUID.
2. Convert the document to PDF and capture the converted file's UUID.
3. Generate a JPG thumbnail of the document's first page.
4. Return the CDN URL for the PDF and the CDN URL for the thumbnail.
If any command exits non-zero, stop and tell me the exit code and what it
means instead of retrying blindly. Do not delete anything.Both prompts are shaped the same way, and that shape isย what the CLIโs design makes possible:
-
Points at
api-schemafirst: the agent verifies the command surface atย runtime instead ofย relying onย syntax you typed, soย the prompt keeps working asย the CLIย changes. -
Requires
--json: the agent gets structured output itย can parse and thread each UUID from one step toย the next. -
Sets aย failure rule: itย tells the agent toย stop onย aย non-zero exit code and report what itย means, which the agent looks upย in
api-schemarather than looping onย aย bad command. -
Draws aย safety line: โDoย not delete anythingโ keeps aย broadly permissioned agent from taking aย destructive step you didnโt ask for.
Swap inย your own folder orย document, and the same prompts drive any ofย the four agents.
Conclusion
In this guide, youโve learned how to connect the Uploadcare CLI to AI agents:
installing the single binary, authenticating with your API keys,
and giving each agent anย instruction file that points itย at uploadcare api-schema plus aย terminal permission toย run the command.
Youโve also walked two end-to-end examples where anย agent uploads aย folder ofย product images and converts aย document toย PDF with aย thumbnail,
returning CDN URLs without anย SDK.
The through-line isย that the CLIย is self-describing: because the agent reads the command surface from api-schema atย runtime,
your setup keeps working asย the CLIย grows. From here, aย few directions toย explore:
- Batch migrations: Have the agent combine
--page-all,--from-stdin, and--dry-runtoย preview and run bulk file operations safely. - CI/CDย reuse: Drop the same commands into aย GitHub Actions step, where the deterministic exit codes make failures easy toย catch.
- Metadata-driven workflows: Use
uploadcare metadata setandgetsoย the agent can tag and later find files byย environment orย source.
Toย get started, Install the Uploadcare CLI, point your agent atย it, and sign upย for aย free account toย get your API keys. The full command reference isย available inย the CLI documentation.
Frequently asked questions
Which AIย coding agents work with the Uploadcare CLI?
Any agent that can run shell commands. That includes Cursor, Claude Code, GitHub Copilot, and OpenAI Codex, plus any LLM-based tool that shells out toย aย subprocess. Because the CLIย is aย single binary with deterministic exit codes and JSON output, itย behaves the same whether aย human orย anย agent runsย it.
How does the agent know which Uploadcare commands are available?
Itย runs uploadcare api-schema, which outputs the full CLI surface asย JSON:
every command path, its flags and arguments, the JSON fields each command can return, and agent-specific usage guidance.
The agent reads that schema instead ofย guessing method names orย parsing help text, soย itย composes valid commands onย the first try.
Doย Iย need aย wrapper, plugin, orย SDK toย use the CLI with anย agent?
No. The CLIย is aย standalone binary. You installย it, export your API keys, and let the agent invokeย it.
Thereโs noย SDK toย import and noย plugin toย maintain. The agent calls uploadcare the same way itย would call git or curl.
What happens ifย the agent runs aย destructive operation?
For destructive commands like file delete, add the --dry-run flag toย preview the effect before anything changes.
Combined with your agentโs own command approval orย auto-run allowlist,
you can require confirmation for writes and deletes while letting read-only commands run freely.
Can Iย use the same CLI commands inย CI/CD?
Yes. The commands that work inย anย agentโs terminal work unchanged inย aย shell script orย aย GitHub Actions step.
The deterministic exit codes (0 success, 1 API error, 2 usage error, 3 auth error) let aย pipeline branch onย failure without parsing output,
soย the same file workflow serves both your agent and your build.