Temporal CLI

To install the CLI manually:

1. Download the appropriate archive for your OS and architecture from the Temporal download service:
   • Linux amd64
   • Linux arm64
   • macOS amd64
   • macOS arm64
   • Windows amd64
2. Extract the downloaded archive.
3. Add the temporal binary (or temporal.exe on Windows) to your PATH.

To build the Temporal CLI from the source code:

1. Install Go.
2. Clone the repository.
3. Navigate to the cloned directory and run the build command:

go build ./cmd/temporal

The resulting executable will be named temporal (or temporal.exe on Windows).

On macOS or Linux systems with Homebrew installed, you can install the Temporal CLI using the following command:

brew install temporal

You can run the Temporal CLI using Docker. To verify the installation and view help documentation, use:

docker run --rm temporalio/temporal --help

To run the Temporal development server so that it is accessible from your host system, you must listen on the external IP (0.0.0.0) and forward the necessary ports (7233 for the server and 8233 for the UI):

docker run --rm -p 7233:7233 -p 8233:8233 temporalio/temporal:latest server start-dev --ip 0.0.0.0

Once running, the Temporal UI will be accessible at http://localhost:8233/.

If a CodecEndpoint is provided in ClientOptions, the ClientOptionsBuilder configures a remote payload codec. This involves:

1. Creating a converter.RemotePayloadCodec.
2. Injecting a gRPC unary interceptor into the client's DialOptions.
3. Setting specific headers (like X-Namespace, Authorization, and custom CodecHeader values) on the outgoing HTTP requests to the codec endpoint.

The resulting PayloadCodec is also attached to the ClientOptionsBuilder.PayloadCodec field so it can be used for manual decoding of nested payloads.

The Temporal CLI supports using a placeholder in the connection address to dynamically inject the namespace. The placeholder is ${namespace}.

When Build() is called, the builder replaces all occurrences of ${namespace} in the Address field with the value provided in ClientOptions.Namespace.

Note: If you use a templated address and are using OAuth, you must explicitly set the --namespace flag or have it configured in your profile, otherwise Build() will return an error.

The Temporal CLI uses configuration profiles to manage different connection settings (e.g., different Temporal clusters). You can interact with these profiles using the config command group.

Profile Selection

Profiles are selected in the following order of precedence:

1. The --profile CLI flag.
2. The TEMPORAL_PROFILE environment variable.
3. The default profile (defined by the underlying SDK).

Available Commands

• List profiles: See all available profiles in your configuration file.
• Get property: Retrieve the value of a specific configuration setting within a profile.
• Set property: Update or create a configuration setting.
• Delete property: Remove a specific configuration setting.
• Delete profile: Remove an entire profile (requires explicit --profile flag to prevent accidental deletion of the default profile).

Use StoreClientOAuth to save or update OAuth 2.0 credentials in the Temporal configuration file. This function is designed to be non-destructive; it preserves existing configuration in the file and only modifies the specified profile's oauth and address fields.

• To update/add OAuth: Provide an OAuthConfig in StoreClientOAuthOptions.
• To remove OAuth: Provide nil for the OAuth field in StoreClientOAuthOptions.
• To update the server address: Provide the Address field; if OAuth is also provided, both will be updated.

err := cliext.StoreClientOAuth(cliext.StoreClientOAuthOptions{
    ProfileName: "my-profile",
    OAuth: &cliext.OAuthConfig{
        ClientConfig: &oauth2.Config{ /* ... */ },
        Token:        &oauth2.Token{ /* ... */ },
    },
    Address: "localhost:7233",
})

Call the Stop() method on a *Server instance to gracefully shut down both the Temporal server and the UI server (if it was started).

server.Stop()

Use LoadClientOAuth to retrieve OAuth 2.0 client configuration and tokens from a TOML configuration file for a specific profile. The function resolves the configuration file path and profile name using the provided options or environment variables (TEMPORAL_CONFIG_FILE and TEMPORAL_PROFILE).

If the profile is not configured in the file, the returned OAuth field in the result will be nil.

import "github.com/temporalio/temporalio/cli/cliext"

result, err := cliext.LoadClientOAuth(cliext.LoadClientOAuthOptions{
    ConfigFilePath: "/path/to/config.toml",
    ProfileName:    "my-profile",
})
if err != nil {
    // handle error
}
if result.OAuth != nil {
    // use result.OAuth.ClientConfig and result.OAuth.Token
}

The ClientOptions struct defines flags for connecting to a Temporal Service. It includes settings for the gRPC endpoint, namespaces, authentication (API keys, TLS/mTLS), and Remote Codec configuration. Use BuildFlags to attach these to a *pflag.FlagSet.

// Example of how ClientOptions might be used in a command implementation
var opts ClientOptions
fs := pflag.NewFlagSet("my-command", pflag.ContinueOnError)
opts.BuildFlags(fs)
// fs now contains flags like --address, --namespace, --tls, --api-key, etc.