use-cases/agent-friendly-clis.md +171 −0 added
1# Create a CLI Codex can use | Codex use cases
2
3Codex use cases
4
5
6
7
8
9Codex use case
10
11# Create a CLI Codex can use
12
13Give Codex a composable command for an API, log source, export, or team script.
14
15Difficulty **Intermediate**
16
17Time horizon **1h**
18
19Ask Codex to create a composable CLI it can run from any folder, combine with repo scripts, use to download files, and remember through a companion skill.
20
21## Best for
22
23- Repeated work where Codex needs to search, read, download from, or safely write to the same service, export, local archive, or repo script.
24- Agent tools that need paged search, exact reads by ID, predictable JSON, downloaded files, local indexes, or draft-before-write commands.
25
26# Contents
27
28[← All use cases](https://developers.openai.com/codex/use-cases)
29
30Copy page [Export as PDF](https://developers.openai.com/codex/use-cases/agent-friendly-clis/?export=pdf)
31
32Ask Codex to create a composable CLI it can run from any folder, combine with repo scripts, use to download files, and remember through a companion skill.
33
34Intermediate
35
361h
37
38Related links
39
40[Codex skills](https://developers.openai.com/codex/skills) [Create custom skills](https://developers.openai.com/codex/skills/create-skill)
41
42## Best for
43
44- Repeated work where Codex needs to search, read, download from, or safely write to the same service, export, local archive, or repo script.
45- Agent tools that need paged search, exact reads by ID, predictable JSON, downloaded files, local indexes, or draft-before-write commands.
46
47## Skills & Plugins
48
49- [Cli Creator](https://github.com/openai/skills/tree/main/skills/.curated/cli-creator)
50
51 Design the command surface, build the CLI, add setup and auth checks, install the command on PATH, and verify it from another folder.
52- [Skill Creator](https://github.com/openai/skills/tree/main/skills/.system/skill-creator)
53
54 Create the companion skill that teaches later Codex tasks which CLI commands to run first and which write actions require approval.
55
56| Skill | Why use it |
57| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
58| [Cli Creator](https://github.com/openai/skills/tree/main/skills/.curated/cli-creator) | Design the command surface, build the CLI, add setup and auth checks, install the command on PATH, and verify it from another folder. |
59| [Skill Creator](https://github.com/openai/skills/tree/main/skills/.system/skill-creator) | Create the companion skill that teaches later Codex tasks which CLI commands to run first and which write actions require approval. |
60
61## Starter prompt
62
63Use $cli-creator to create a CLI you can use, and use $skill-creator to create the companion skill in this same thread.
64Source to learn from: [docs URL, OpenAPI spec, redacted curl command, existing script path, log folder, CSV or JSON export, SQLite database path, or pasted --help output].
65First job the CLI should support: [download failed CI logs from a build URL, search support tickets and read one by ID, query an admin API, read a local database, or run one step from an existing script].
66Optional write job: [create a draft comment, upload media, retry a failed job, or read-only for now].
67 Command name: [cli-name, or recommend one].
68Before coding, show me the proposed command surface and ask only for missing details that would block the build.
69
70[Open in the Codex app](codex://new?prompt=Use+%24cli-creator+to+create+a+CLI+you+can+use%2C+and+use+%24skill-creator+to+create+the+companion+skill+in+this+same+thread.%0A%0ASource+to+learn+from%3A+%5Bdocs+URL%2C+OpenAPI+spec%2C+redacted+curl+command%2C+existing+script+path%2C+log+folder%2C+CSV+or+JSON+export%2C+SQLite+database+path%2C+or+pasted+--help+output%5D.%0A%0AFirst+job+the+CLI+should+support%3A+%5Bdownload+failed+CI+logs+from+a+build+URL%2C+search+support+tickets+and+read+one+by+ID%2C+query+an+admin+API%2C+read+a+local+database%2C+or+run+one+step+from+an+existing+script%5D.%0A%0AOptional+write+job%3A+%5Bcreate+a+draft+comment%2C+upload+media%2C+retry+a+failed+job%2C+or+read-only+for+now%5D.%0A%0ACommand+name%3A+%5Bcli-name%2C+or+recommend+one%5D.%0A%0ABefore+coding%2C+show+me+the+proposed+command+surface+and+ask+only+for+missing+details+that+would+block+the+build. "Open in the Codex app")
71
72Use $cli-creator to create a CLI you can use, and use $skill-creator to create the companion skill in this same thread.
73Source to learn from: [docs URL, OpenAPI spec, redacted curl command, existing script path, log folder, CSV or JSON export, SQLite database path, or pasted --help output].
74First job the CLI should support: [download failed CI logs from a build URL, search support tickets and read one by ID, query an admin API, read a local database, or run one step from an existing script].
75Optional write job: [create a draft comment, upload media, retry a failed job, or read-only for now].
76 Command name: [cli-name, or recommend one].
77Before coding, show me the proposed command surface and ask only for missing details that would block the build.
78
79## Introduction
80
81When Codex keeps using the same API, log source, exported inbox, local database, or team script, give that work a composable interface: a command it can run from any folder, inspect, narrow, and combine with `git`, `gh`, `rg`, tests, and repo scripts.
82
83Add a companion skill that records when Codex should use the CLI, what to run first, how to keep output small, where downloaded files land, and which write commands need approval.
84
85In this workflow, `$cli-creator` helps Codex build the command. `$skill-creator` helps Codex save a reusable skill such as `$ci-logs`, which future tasks can invoke by name.
86
87## How to use
88
891. [Decide whether the job needs a CLI](#choose-what-the-cli-should-do)
902. [Share the source Codex should learn from](#share-the-docs-files-or-commands)
913. [Run `$cli-creator`](#ask-codex-to-build-the-cli-and-skill)
924. [Test the installed command](#verify-the-command-works-from-any-folder)
935. [Invoke the saved skill later](#use-the-skill-later)
94
95## Choose what the CLI should do
96
97Start with the thing you want Codex to do, not the technology you want it to write. A good CLI turns a repeated read, search, download, export, draft, upload, poll, or safe write into a command Codex can run from any repo.
98
99| Situation | What Codex can do with the CLI |
100| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
101| **CI logs live behind a build page.** | Take a build URL, download failed job logs to `./logs`, and return file paths plus short snippets. |
102| **Support tickets arrive as a weekly export.** | Index the newest CSV or JSON export, search by customer or phrase, and read one ticket by stable ID. |
103| **An API response is too large for context.** | List only the fields it needs, read the full object by ID, and export the complete response to a file. |
104| **A Slack export has long threads.** | Search with `--limit`, read one thread, and return nearby context instead of the whole archive. |
105| **A team script runs four different steps.** | Split setup, discovery, download, draft, upload, poll, and live write into separate commands. |
106| **A plugin finds the record, but Codex needs a file.** | Keep the plugin in the thread; use a CLI to download the attachment, trace, report, video, or log bundle and return the path. |
107
108## Share the docs, files, or commands
109
110Codex needs something concrete to learn from: docs or OpenAPI, a redacted curl command, an export or database path, a log folder, or an existing script. If you want the CLI to follow a familiar style, paste a short `--help` output from `gh`, `kubectl`, or your team's own tool.
111
112If the command needs auth, tell Codex the environment variable name, config file path, or login flow it should support. Set the secret yourself in your shell or config file. Do not paste secrets into the thread. Ask Codex to make the CLI's setup check fail clearly when auth is missing.
113
114## Ask Codex to build the CLI and skill
115
116Use the starter prompt on this page. Fill in the source Codex should learn from and the first job the CLI should support.
117
118Before Codex writes code, it should show the proposed command surface and ask only for missing details that would block the build.
119
120## Verify the command works from any folder
121
122Codex should not stop after `cargo run`, `python path/to/script.py`, or an uninstalled package command. Ask it to test the installed command from another repo or a temporary folder, the way a later task will use it.
123
124**Test the CLI like a future agent**
125
126Test [cli-name] the way you would use it in a future task.
127Please show proof that:
128- command -v [cli-name] succeeds from outside the CLI source folder
129- [cli-name] --help explains the main commands
130- the setup/auth check runs
131- one safe discovery, list, or search command works
132- one exact read command works with an ID from the discovery result
133- any large log, export, trace, or payload writes to a file and returns the path
134- live write commands are not run unless I explicitly approved them
135Then read the companion skill and tell me the shortest prompt I should use when I need this CLI again.
136
137If Codex returns a giant JSON blob, ask it to narrow the default response and add a file export for full payloads. If it forgets the approval boundary, ask it to update the companion skill before you use it in another thread.
138
139## Use the skill later
140
141When you need the CLI again, invoke the skill instead of pasting the docs again:
142
143Use $ci-logs to download the failed logs for this build URL and tell me the first failing step.
144
145Use $support-export to search this week's refund complaints and read the three highest-value tickets.
146
147Use $admin-api to find this user's workspace, read the billing record, and draft a safe account note.
148
149For recurring work, test the skill once in a normal thread, then ask Codex to turn that same invocation into an automation.
150
151## Related use cases
152
153[
154
155### Create browser-based games
156
157Use Codex to turn a game brief into first a well-defined plan, and then a real browser-based...
158
159Engineering Code](https://developers.openai.com/codex/use-cases/browser-games)[
160
161### Deploy an app or website
162
163Use Codex with Build Web Apps and Vercel to turn a repo, screenshot, design, or rough app...
164
165Front-end Integrations](https://developers.openai.com/codex/use-cases/deploy-app-or-website)[
166
167### Refactor your codebase
168
169Use Codex to remove dead code, untangle large files, collapse duplicated logic, and...
170
171Engineering Code](https://developers.openai.com/codex/use-cases/refactor-your-codebase)