CLI And Commands

Purpose and Scope

CLI and commands are a practical boundary between AI SDK applications and developer workstations, hosted coding environments, or sandboxed execution systems. In this repository’s documentation, the boundary appears in two complementary forms: community providers that route model calls through local command-line clients, and tools that let a model request command-like actions through the AI SDK Core tool loop. The goal of this page is to show how those pieces fit the same provider-agnostic programming model instead of treating command-line model access as a separate integration path.

Sources: content/providers/05-community-providers/13-codex-cli.mdx, content/providers/05-community-providers/18-gemini-cli.mdx, content/docs/03-ai-sdk-core/01-overview.mdx, content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

AI SDK Core standardizes prompts, settings, text generation, structured output, and tool usage across providers. That means a provider backed by a CLI can still be passed to generateText or streamText like any other language model. It also means command execution should be modeled as an explicit tool with an input schema, description, and optional execute function, rather than as hidden side effects inside a prompt. This distinction is important for agent safety: the model can select tools, but the application owns validation, sandboxing, approval policy, and stopping conditions.

Core Primitives

A CLI provider is an adapter that lets an AI SDK model call be fulfilled through a local or library-backed command-line ecosystem. The Codex CLI provider exposes codexCli and createCodexCli, while the Gemini CLI provider exposes createGeminiProvider. After a provider instance is created, the application selects a model by calling the provider function with a model ID, then passes that model into AI SDK Core generation functions. This keeps the command-line authentication and runtime details outside the call site that asks the model to generate text.

Sources: content/providers/05-community-providers/13-codex-cli.mdx, content/providers/05-community-providers/18-gemini-cli.mdx, content/docs/03-ai-sdk-core/05-generating-text.mdx

A command tool is different from a CLI provider. A provider supplies the model; a tool supplies an action the model can request. The tool-calling documentation defines tools with description, inputSchema, optional execute, and optional strict. It also shows a shell-style tool whose description can depend on toolsContext and experimental_sandbox, and whose execution calls experimental_sandbox.run({ command }). This pattern makes command execution inspectable: the command is structured input, the result is a tool result, and the surrounding generation can stop according to stopWhen. Sources: content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

Relevant Source Files

• content/providers/05-community-providers/13-codex-cli.mdx - Documents the Codex CLI community provider, installation commands, provider instance creation, per-model settings, model IDs, reasoning configuration, approval modes, sandbox modes, MCP server configuration, and a generateText example.
• content/providers/05-community-providers/18-gemini-cli.mdx - Documents the Gemini CLI community provider, installation commands, authentication modes, provider creation, supported models, and model settings such as temperature, token limits, and thinking configuration.
• content/docs/03-ai-sdk-core/01-overview.mdx - Establishes AI SDK Core as the standardized layer for text generation, structured data generation, and tool usage across different models and providers.
• content/docs/03-ai-sdk-core/05-generating-text.mdx - Defines generateText and streamText, shows the standard model-and-prompt call shape, and lists result metadata relevant to command-oriented workflows.
• content/docs/03-ai-sdk-core/10-generating-structured-data.mdx - Explains structured output with Output.object() and notes that structured generation can be combined with tool calling in the same request.
• content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx - Defines the public tool contract, multi-step tool calls, stopWhen, dynamic descriptions, toolsContext, and experimental_sandbox for command-like execution.

System-to-Code Mapping

The Codex CLI provider page maps command-line model access to the AI SDK provider pattern. Installation is shown for common package managers, and compatibility distinguishes AI SDK v6 from older v5 package tags. The default codexCli provider instance is suitable when defaults are enough, while createCodexCli lets applications define shared settings such as reasoningEffort, approvalMode, sandboxMode, mcpServers, verbose, and logger. Per-model settings can override those defaults when a specific request needs a different reasoning depth or approval posture.

Sources: content/providers/05-community-providers/13-codex-cli.mdx

The Gemini CLI provider page follows the same overall shape but emphasizes authentication setup. createGeminiProvider can be configured with authType: 'oauth-personal', API key authentication, Vertex AI settings, or a Google Auth Library instance. The provider then creates models such as gemini-2.5-pro or preview Gemini 3 variants. Because the resulting object is still an AI SDK language model, the application can use the same generateText example shape as other providers while relying on Gemini CLI credentials or Google authentication under the provider layer.

Sources: content/providers/05-community-providers/18-gemini-cli.mdx, content/docs/03-ai-sdk-core/05-generating-text.mdx

Execution Flow

A command-oriented model call usually starts by choosing the provider boundary. If the command-line client is only used to authenticate and dispatch model calls, create a CLI provider instance and pass its model into generateText or streamText. If the model needs to request real actions, define one or more tools and pass them in the tools object. The model may then emit a tool call, the SDK validates the call against the schema, the application executes or forwards it, and the result becomes part of the multi-step generation.

Sources: content/docs/03-ai-sdk-core/05-generating-text.mdx, content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

import { generateText, tool, isStepCount } from 'ai';
import { z } from 'zod';
import { codexCli } from 'ai-sdk-provider-codex-cli';
 
const result = await generateText({
  model: codexCli('gpt-5.2-codex'),
  tools: {
    shell: tool({
      description: 'Run a safe project command.',
      inputSchema: z.object({ command: z.string() }),
      execute: async ({ command }, { experimental_sandbox }) => {
        if (!experimental_sandbox) throw new Error('Sandbox required');
        return experimental_sandbox.run({ command });
      },
    }),
  },
  stopWhen: isStepCount(5),
  prompt: 'List the project files and summarize the package scripts.',
});

Structured output can be added to this same flow when the command result should become validated data. The structured data documentation places Output.object() on generateText and streamText, with Zod, Valibot, or JSON schemas defining the expected shape. It also notes that structured output counts as a step in the multi-turn execution model when combined with tools. For command workflows, that detail matters because stopWhen must leave enough room for model calls, tool execution, and the final structured response.

Sources: content/docs/03-ai-sdk-core/10-generating-structured-data.mdx, content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

Command and Provider Reference

Implementation Details

The safest way to think about CLI-backed agents is to keep model transport, command authorization, and command execution separate. CLI providers handle transport and credentials. Tool definitions handle the model-visible command surface. Approval modes, sandbox modes, and sandbox execution decide whether a requested action should run and where it can run. The Codex CLI provider settings explicitly name approval and sandbox concerns, while AI SDK Core tools show how to attach an execution sandbox to a shell-like tool. These are complementary layers, not replacements for each other.

Sources: content/providers/05-community-providers/13-codex-cli.mdx, content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

The official tool registry snippets reinforce the same public shape for command-oriented add-ons: a tool entry has a package name, install commands for pnpm, npm, yarn, and bun, optional environment variable metadata, and a code example that passes the tool into generateText with a step limit. When documenting or packaging a command tool, mirror that reader experience. Show how to install it, what credentials it needs, which AI SDK function it works with, and how the caller limits multi-step execution.

Next Steps

Start with a CLI provider when your main requirement is model access through existing Codex or Gemini credentials. Add AI SDK Core tools when the model must request actions such as shell commands, code execution, search, or project inspection. For production agent workflows, define narrow schemas, use explicit stopWhen limits, prefer sandbox-backed execution, and document approval behavior close to the tool definition. Then read the related pages on tools, sandboxing, providers, and core generation to decide where each responsibility belongs.