CLI And Commands

Purpose and Scope

The OpenAI CLI is the shell-native way to interact with the OpenAI API from a terminal. In an agent workflow, a command-line interface is useful when work should be repeatable, inspectable, and easy to compose with files, pipes, environment variables, and CI jobs. The official CLI documentation positions the openai command for one-off requests, artifact generation, structured extraction, Admin API operations, and scripts that agents or developers can rerun deliberately. This page explains that command primitive alongside the command-oriented validation code present in the openai-node repository.

The important boundary is that openai-node is the TypeScript and JavaScript SDK, while the current OpenAI CLI is installed separately with Homebrew or Go. The repository evidence for this page is not an implementation of the openai binary. Instead, it shows how this SDK project treats commands as a serious integration surface: a TypeScript ecosystem test runner installs packaged SDK builds, executes package-manager commands, runs type checks and tests, starts optional network plumbing, and can deploy runtime fixtures. Sources: ecosystem-tests/cli.ts

For agent-framework readers, think of commands as a bridge between model-driven planning and deterministic execution. A subagent may explore a codebase, compare alternatives, or make judgment calls; a CLI command should be the repeatable action that follows from that judgment. The official OpenAI CLI guidance makes the same distinction for Codex-style workflows: use the CLI for batch extraction, file transforms, artifact generation, and explicit model or endpoint selection, while reserving subagents for exploratory reasoning and review.

Relevant Source Files

• ecosystem-tests/cli.ts - Defines the repository's ecosystem-test command runner, including project-specific runners, package installation steps, shell command execution through execa, argument parsing through yargs, live-test and deploy gates, and proxy setup for validating SDK behavior across runtimes.

The single requested source file is useful because it demonstrates the repository's own command vocabulary. The runner names concrete environments such as node-ts-cjs, node-ts-esm, node-js, ts-browser-webpack, browser-direct-import, vercel-edge, cloudflare-worker, and bun. Each runner encodes the commands that prove a packaged SDK works in that environment, such as npm run tsc, npm run build, npm run test:ci, bun install, bun test, vercel deploy --prod --force, and Cloudflare deploy scripts. Sources: ecosystem-tests/cli.ts

Core Primitives

The CLI primitive begins with authentication. The official OpenAI CLI reads OPENAI_API_KEY for ordinary API calls, OPENAI_ADMIN_KEY for Admin API endpoints, and OPENAI_BASE_URL when a script must target a different API host. These variables match the shell-first model: configuration is external to the command invocation, so scripts can run consistently in local terminals, CI systems, and agent sandboxes without embedding secrets in source files. In practice, an agent should treat these variables as preconditions and never print secret values back into logs.

Installation is separate from installing this JavaScript SDK. The official CLI can be installed with brew install openai/tools/openai or with Go using go install 'github.com/openai/openai-cli/cmd/openai@latest'. By contrast, the TypeScript SDK is consumed as the openai package and imported into application code. When documenting or automating workflows, be precise about whether openai means the shell command, the npm package name, or the default TypeScript class imported from the package.

Commands also have output contracts. The official CLI exposes global formatting choices such as --format with values including auto, json, jsonl, pretty, raw, yaml, and explore, plus transformation support for extracting or reshaping response data. These options matter for agents because a command that emits stable JSON or JSONL is easier to validate, diff, store, and feed into a later step than a command that only prints human-oriented prose.

System-to-Code Mapping

Although the OpenAI CLI itself is not implemented in this repository, ecosystem-tests/cli.ts shows how the SDK maintainers model reliable command execution. The file imports execa for subprocess execution, yargs for parsing command-line arguments, fs/promises and path for filesystem setup, and Node networking modules for an optional proxy. That composition is a practical blueprint for scripts around the SDK: parse explicit flags, prepare an isolated working directory, install the artifact under test, run deterministic checks, and gate live or deploy operations behind state. Sources: ecosystem-tests/cli.ts

The runner's projectRunners object is the main dispatch table. Shared Node TypeScript projects use a default runner that installs the package, runs npm run tsc, and only runs tests when live mode is enabled. JavaScript-only projects run node test.js. Browser-oriented projects add bundling or direct import setup before their checks. Edge fixtures add build, live test, and optional deploy phases. Bun has its own installation path, either from npm or from a locally packed tarball named openai.tgz. Sources: ecosystem-tests/cli.ts

That structure is useful when turning CLI work into an agent operation. A command should declare which environment it targets, what setup it needs, what validation follows, and which phases require credentials or external services. The test runner follows this pattern by separating type checks from live tests and deployments. It also uses environment variables such as OPENAI_API_KEY and an internally assigned ECOSYSTEM_TESTS_PROXY rather than hard-coding network configuration into command arguments.

Execution Flow

A practical terminal workflow usually starts with credentials, then command installation, then a narrow request. For example, a developer can export OPENAI_API_KEY, install the official CLI, and use CLI commands for terminal-native API work. If the task is part of this repository's validation workflow rather than a product API request, the ecosystem runner installs a candidate SDK package into fixture projects and executes each fixture's own package scripts. The distinction keeps application usage separate from release confidence.

export OPENAI_API_KEY="sk-..."
brew install openai/tools/openai
# or: go install 'github.com/openai/openai-cli/cmd/openai@latest'

For repository validation, the command pattern is more like a matrix runner than an end-user API call. A local package is prepared as openai.tgz, installed into a fixture, and then commands such as npm run tsc, npm run build, or bun test confirm that the SDK behaves in that runtime. Browser direct-import setup even rewrites public/node_modules as a symlink before type checking, showing that command flows may need filesystem preparation before a model or API request is ever made. Sources: ecosystem-tests/cli.ts

Live and deployment phases are intentionally gated. The ecosystem runner checks state before running live tests, Vercel deployments, Cloudflare Worker deployments, or proxy-dependent paths. That is the right default for agentic command execution too: cheap deterministic checks can run frequently, while commands that call external services, consume quota, or publish deploy artifacts should require an explicit mode, flag, or approval boundary.

Command Reference

When using commands inside an agent workflow, prefer a small command surface with explicit inputs and stable outputs. Put secrets in the environment, request JSON or JSONL when the next step is automated, and capture both stdout and failure status. For SDK repository work, follow the ecosystem runner's pattern: install first, type-check before live calls, and make deploy behavior opt-in.

Next Steps

Use this page when deciding whether a task belongs in a terminal command, application code, or a subagent. For direct TypeScript or JavaScript API calls, continue to the developer quickstart and client configuration pages. For command workflows that touch Admin endpoints, read the Admin and organization reference so you know which operations require admin authentication. For runtime-specific scripts, pair this page with browser, edge, and deployment guidance before putting commands into CI or an agent sandbox.