Temporal CLI for coding agents

When a coding agent works on a service that uses Temporal, the temporal command-line interface (CLI) lets it start a local Temporal server and inspect workflow executions. A workflow is code that coordinates work over time. Temporal records the workflow's progress, so a workflow resumes automatically after a crash. The CLI helps an agent check what the service is doing. The service still needs workflow code and a worker, a process that runs that code, to perform application work.

For a concrete task, an agent can start a local development server and check whether the service has launched any workflows. These commands stay local. The workflow-listing command is read-only: it does not start, cancel, or change workflow executions.

What the CLI does

Temporal is a durable execution platform for coordinating work that may run for a long time or need to recover after failures. A workflow defines the durable sequence of steps. An activity performs work outside that sequence, such as making an API call or calling a language model. Temporal’s AI documentation describes integrations with agent frameworks, including the OpenAI Agents SDK, Google ADK, and LangGraph.

The CLI supports local development and operations such as inspecting workflows and managing namespaces, which group workflow executions; task queues, which workers use to receive work; and schedules, which define when workflows start. It does not build an AI agent by itself. Your code must define the workflow and activities, and a worker must run that code. Temporal’s page on common CLI operations shows the commands you are most likely to use. The command reference lists all of them.

Start a local server

On macOS with Homebrew, install the CLI:

brew install temporal

The install guide also has downloads for Linux and Windows and a Docker image. Start a local development server from a terminal:

temporal server start-dev

Leave the terminal running while you work. The command runs a local Temporal service; it does not connect to Temporal Cloud or change a Cloud namespace. The install guide says it creates the default namespace and keeps its data in an in-memory database. The service listens on localhost:7233, and the Web UI is at http://localhost:8233. Add --db-filename temporal.db if you want the data to stay after a restart. In a second terminal, list executions in the local default namespace:

temporal workflow list --namespace default --output json

The command displays workflow executions recorded in that namespace. The --output json flag gives output a script or agent can parse, and --limit caps how many executions it shows. A freshly started local server has no executions until a client starts one. To inspect your service’s workflows, start the service’s existing worker and run the code that launches a workflow, then run the list command again. Listing executions is read-only; the CLI does not modify workflow state here.

An agent can use this example to answer a focused debugging question: “Did the local service start a workflow?” It should report what the CLI returns and avoid inferring that a workflow failed only because the list is empty. The service may not have started one yet, or it may be connected to a different server or namespace.

Keep local and Cloud access separate

The example uses the local development server, so it does not require Temporal Cloud credentials. For Cloud access, configure the authentication method and connection details required for the target namespace. The Temporal Cloud guide for the CLI recommends API keys or mutual TLS (mTLS), a certificate-based authentication method, for agents and scripts. Keep credentials in a configuration profile or environment variable, not in an agent prompt or command text that could be logged.

Before running a command, check whether its target is the local server or a Cloud endpoint. Without flags, the CLI connects to localhost:7233 and the default namespace. Environment variables like TEMPORAL_ADDRESS and TEMPORAL_NAMESPACE, or a profile in the CLI's config file, can point the same command at another server. The environment configuration reference lists these settings.

Treat workflow mutations carefully

The CLI also has commands that change workflow state, such as starting, signaling, canceling, or terminating executions. Temporal’s workflow command reference describes these operations, but workflow mutations do not have a preview step. A command that starts or terminates a workflow acts on the selected server when run. When you use --query to act on many workflows at once, the CLI asks for confirmation unless --yes is set. Keep an inspection task to read-only commands unless the user explicitly requests a state change and confirms the target.

A useful agent prompt for the local example is:

Start the local Temporal development server if it is not already running, then list workflow executions in the default namespace. Do not start, signal, cancel, or terminate any workflow. Report whether the list contains executions.