automation library

Pulumi Automation API for Dart.

This library provides a Dart interface for driving Pulumi CLI workflows in code. It follows the same conceptual model as other Pulumi language SDKs: a LocalWorkspace that owns execution context and a Stack handle for lifecycle operations.

Main entrypoints

  • LocalWorkspace: manage plugins, config, environment, and stack state.
  • Stack: run preview, up, refresh, destroy, and output queries.
  • LocalProgramArgs: target an existing Pulumi program on disk.
  • InlineProgramArgs: define a Pulumi program directly in Dart code.

Use this library when you want Pulumi to be one subsystem in a larger Dart application, CI coordinator, deployment service, or developer tool.

Example

import 'package:pulumi/automation.dart' as automation;

Future<void> main() async {
  final stack = await automation.LocalWorkspace.createOrSelectStack(
    const automation.LocalProgramArgs(
      stackName: 'dev',
      workDir: '.',
    ),
    options: const automation.LocalWorkspaceOptions(
      environmentVariables: {
        'PULUMI_CONFIG_PASSPHRASE': 'pulumi-dart-dev',
      },
    ),
  );

  await stack.setConfig('name', 'dart');
  await stack.preview();
}

For normal infrastructure programs invoked by the Pulumi CLI, import package:pulumi/pulumi.dart instead.

Classes

AutomationConfigValue
Automation config value used by pulumi config commands.
AutomationDestroyResult
Result for pulumi destroy.
AutomationEngineEvent
Pulumi engine event emitted through --event-log.
AutomationImportResource
A resource specification passed to pulumi import.
AutomationImportResult
Result for pulumi import.
AutomationInstallOptions
Options for pulumi install.
AutomationOperationResult
Base result for a Pulumi stack operation.
AutomationOutputValue
Automation stack output value with secret metadata.
AutomationPluginInfo
Metadata for an installed Pulumi plugin.
AutomationPreviewResult
Result for pulumi preview.
AutomationRefreshResult
Result for pulumi refresh.
AutomationRenameResult
Result for pulumi stack rename.
AutomationStackSummary
Summary metadata for a stack returned by pulumi stack ls --json.
AutomationSummaryEvent
Summary event metadata emitted at the end of preview-style operations.
AutomationUpdateSummary
Typed summary metadata for a completed stack operation.
AutomationUpResult
Result for pulumi up.
DockerImageCredentials
Docker image credentials for remote executor images.
ExecutorImage
Remote executor image settings.
InlineProgramArgs
Arguments for source-based inline automation programs.
LocalProgramArgs
Arguments used to bind stack operations to a local Pulumi project directory.
LocalWorkspace
Workspace-backed automation entrypoint for Pulumi CLI operations.
LocalWorkspaceOptions
Options for LocalWorkspace.
PolicyEvent
Policy pack event metadata.
ProjectBackend
Backend configuration in project settings.
ProjectRuntimeInfo
Runtime descriptor for project settings.
ProjectSettings
Typed Pulumi project settings model.
ProjectTemplate
Project template metadata.
ProjectTemplateConfigValue
Project template config entry.
PropertyDiff
Per-property diff metadata from engine events.
PulumiCommandRequest
A Pulumi CLI command invocation.
PulumiCommandResult
A Pulumi CLI command result.
PulumiVersion
Semantic version value for Pulumi CLI version checks.
RemoteGitAuthArgs
Authentication options for a remote Git repository.
RemoteGitProgramArgs
Program source configuration for remote Pulumi operations.
RemoteSecret
Secret wrapper for remote environment variable values.
RemoteWorkspace
Remote workspace helpers for Pulumi Deployments-backed operations.
RemoteWorkspaceOptions
Options used when constructing remote automation command arguments.
Stack
Automation stack handle scoped to a LocalWorkspace.
StackSettings
Typed Pulumi stack settings model.
StepEventMetadata
Step metadata emitted by Pulumi engine events.

Enums

AutomationOpType
Granular resource operation types used in summary change maps.
AutomationUpdateKind
The kind of update operation represented by an AutomationUpdateSummary.
AutomationUpdateResult
The result state represented by an AutomationUpdateSummary.
DiffKind
Kind of difference between old/new values in update events.

Constants

minimumPulumiVersion → const PulumiVersion
Minimum Pulumi CLI version required by the Dart Automation API.
skipVersionCheckVar → const String

Functions

buildRemoteWorkspaceArgs(RemoteGitProgramArgs programArgs, {RemoteWorkspaceOptions options = const RemoteWorkspaceOptions()}) → List<String>
Builds pulumi CLI arguments required for remote operations.
createCommandException(PulumiCommandRequest request, PulumiCommandResult result) → PulumiCommandException
Maps a failed command to a more specific automation error subtype.
isFullyQualifiedStackName(String stackName) → bool
Returns true when stackName is owner/project/stack.
parseAndValidatePulumiVersion(PulumiVersion minimumVersion, String currentVersion, bool optOut) → PulumiVersion?
Parses and validates currentVersion against minimumVersion.
Extracts a Pulumi Console permalink from operation stdout, when present.
validateRemoteGitProgramArgs(RemoteGitProgramArgs args, {bool inheritSettings = false}) → void
Validates remote program arguments using upstream Pulumi Automation rules.

Typedefs

AutomationArgsSerializer = Future<List<String>> Function(String stackName)
Callback used to provide additional CLI arguments per stack operation.
AutomationEngineEventHandler = void Function(AutomationEngineEvent event)
Callback invoked for each parsed Pulumi engine event.
AutomationOpMap = Map<String, int>
Map of operation type to resource change count.
AutomationPostCommandCallback = Future<void> Function(String stackName)
Callback invoked after a stack operation command completes.
PulumiCommandRunner = Future<PulumiCommandResult> Function(PulumiCommandRequest request)
Callback used by automation APIs to execute Pulumi commands.

Exceptions / Errors

AutomationInvalidVersionException
Thrown when a Pulumi CLI version is invalid or incompatible.
CommandError
An error resulting from a failed Pulumi command.
CompilationError
Thrown when a Pulumi program fails to compile/build.
ConcurrentUpdateError
Thrown when another update is already in progress.
InlineSourceRuntimeError
Thrown when inline source execution fails at runtime.
PulumiCommandException
Thrown when a Pulumi CLI command fails and check mode is enabled.
RuntimeError
Thrown when a Pulumi program fails at runtime.
StackAlreadyExistsError
Thrown when creating a stack that already exists.
StackNotFoundError
Thrown when selecting a stack that does not exist.