Skip to main content

​
Synopsis

Execute a Terraform plan on Harness servers using remote execution. This command uploads your local Terraform code, executes it remotely using the configured default pipeline, and streams logs back to your terminal in real-time. 
hc iacm plan --workspace-id <workspace> [flags]

​
Description

The plan command performs a Terraform plan operation remotely:
  1. Fetches workspace configuration from Harness
  2. Packages your local Terraform code based on workspace folder path settings
  3. Uploads the code to Harness with SHA-256 checksum verification
  4. Triggers the default pipeline configured for plan operations
  5. Streams execution logs in real-time
  6. Shows the pipeline execution URL for tracking in the Harness UI
The plan runs on Harness infrastructure, not locally. This means you don’t need Terraform installed on your machine.

​
Flags

​
Required Flags

​
--workspace-id
string
required
Workspace identifier to execute the plan in. The workspace must exist in the specified organization and project.
hc iacm plan --workspace-id my-workspace

​
Optional Flags

​
--org-id
string
Organization identifier. If not specified, uses the organization from your global configuration (set via --org flag or config file).
hc iacm plan --workspace-id my-workspace --org-id my-org
​
--project-id
string
Project identifier. If not specified, uses the project from your global configuration (set via --project flag or config file).
hc iacm plan --workspace-id my-workspace --project-id my-project
​
--target
string[]
Resource targets to plan. Can be specified multiple times. Corresponds to Terraform’s -target flag. Use this to limit the plan to specific resources.
hc iacm plan --workspace-id my-workspace \
  --target aws_instance.web \
  --target aws_s3_bucket.data
​
--replace
string[]
Variable replacements in key=value format. Can be specified multiple times. These are passed as custom arguments to the Terraform execution.
hc iacm plan --workspace-id my-workspace \
  --replace environment=staging \
  --replace region=us-west-2

​
Global Flags

See Global Flags for flags available to all commands, including:
  • --api-url - API base URL
  • --token - Authentication token
  • --account - Account identifier
  • --org - Organization identifier (can be overridden by --org-id)
  • --project - Project identifier (can be overridden by --project-id)
  • --format - Output format
  • --verbose / -v - Enable verbose logging

​
Examples

​
Basic Plan Execution

# Execute a plan with default configuration
hc iacm plan --workspace-id production-workspace
This will:
  1. Use organization and project from your saved configuration
  2. Upload code based on workspace’s repository path
  3. Stream logs to your terminal

​
Plan with Specific Organization and Project

# Override org and project from config
hc iacm plan --workspace-id my-workspace \
  --org-id engineering \
  --project-id infrastructure

​
Plan Specific Resources

# Only plan changes to specific resources
hc iacm plan --workspace-id my-workspace \
  --target aws_instance.web_server \
  --target aws_lb.main
This passes -target aws_instance.web_server -target aws_lb.main to Terraform.

​
Plan with Variable Replacements

# Pass custom variable replacements
hc iacm plan --workspace-id my-workspace \
  --replace aws_instance.web \
  --replace aws_db_instance.primary

​
Plan with Verbose Logging

# Enable detailed HTTP request/response logging
hc iacm plan --workspace-id my-workspace --verbose
Use this for debugging API communication issues.

​
Workflow Details

​
1. Workspace Validation

The command first fetches workspace details: 
Fetching workspace information...
✓ Workspace found
The workspace configuration includes:
  • Repository path (determines what code to upload)
  • Default pipelines (which pipeline to execute)
  • Terraform version and provider configuration

​
2. Default Pipeline Selection

The command looks for a default pipeline in this order:
  1. Workspace-level plan pipeline
  2. Project-level plan pipeline
The plan will execute with the default pipeline: terraform-plan-pipeline...
If no default pipeline is configured, the command will fail. Configure a default pipeline in your workspace or project settings.

​
3. Source Code Packaging

Based on the workspace’s repository_path configuration: If repository path is configured (e.g., terraform/aws): 
The workspace is configured with the folder path terraform/aws,
Harness will upload the following directory and its contents:
/home/user/projects/infrastructure
The CLI finds the repository root by removing the folder path from your current directory. If no repository path is configured: 
The workspace has no configured folder path,
Harness will upload the following directory and its contents
/home/user/projects/infrastructure
The current directory is uploaded.
You’ll be prompted to confirm before upload:
Do you want to continue? (y/N):

​
4. Upload and Execution

Zipping source code...
✓ Source code zipped (1048576 bytes)
Creating remote execution...
✓ Remote execution created
Uploading source code...
✓ Source code uploaded
Triggering pipeline execution...
✓ Pipeline execution triggered
Pipeline execution: https://app.harness.io/ng/#/account/abc/...
The source code is:
  1. Zipped using the same format as HashiCorp’s slug package
  2. Uploaded with SHA-256 checksum verification
  3. Stored securely on Harness servers

​
5. Log Streaming

Getting log token...
Streaming logs...

=== Pipeline Execution Logs ===
========================== Starting stage Terraform Plan ==========================
========================== Starting step Initialize ==========================
INFO 03/03/2026 14:23:45 Initializing Terraform...
INFO 03/03/2026 14:23:46 Terraform 1.5.0
========================== Starting step Plan ==========================
INFO 03/03/2026 14:23:47 Running terraform plan...
INFO 03/03/2026 14:23:48 Terraform will perform the following actions:
...
Log streaming:
  • Shows stages and steps as they execute
  • For running steps: streams logs in real-time via SSE
  • For completed steps: fetches and displays logs immediately
  • Continues until pipeline completes
Logs are formatted with level, timestamp, and message for easy reading.

​
6. Interruption Handling

Press Ctrl+C to interrupt: 
^C
Interrupted. Cleaning up...
The CLI will:
  • Stop streaming logs
  • Clean up resources
  • Exit gracefully
Interrupting the CLI does NOT stop the remote pipeline execution. The plan continues running on Harness servers. Check the pipeline execution URL to see the final status.

​
Remote Execution Details

​
Architecture

When you run hc iacm plan:
  1. Client Side (your machine):
    • Packages source code
    • Uploads to Harness
    • Streams logs
  2. Harness Side (remote):
    • Receives and stores code
    • Triggers pipeline execution
    • Runs Terraform on secure infrastructure
    • Streams logs back to client

​
Security

  • Source code is transmitted over HTTPS
  • SHA-256 checksum verifies integrity
  • Authentication token required for all operations
  • Separate log service token for streaming
  • Code is isolated per execution

​
Pipeline Integration

The remote execution:
  • Uses the default pipeline configured in your workspace
  • Can access workspace environment variables
  • Runs with workspace’s Terraform version
  • Has access to workspace’s provider credentials
  • Stores state according to workspace configuration

​
Troubleshooting

The --workspace-id flag is mandatory. Provide the identifier of the workspace to execute the plan in:
hc iacm plan --workspace-id my-workspace
Configure a default pipeline for plan operations:
  1. Go to your workspace settings in Harness UI
  2. Navigate to Default Pipelines section
  3. Set a pipeline for “plan” operations
Or configure at project level if you want to use the same pipeline across workspaces.
The workspace’s repository_path doesn’t exist in your current directory:Option 1: Navigate to the correct directory
cd /path/to/repository
hc iacm plan --workspace-id my-workspace
Option 2: Update the workspace’s repository path in Harness UI
You need to authenticate with Harness:
hc auth login
Or provide credentials via flags:
hc iacm plan --workspace-id my-workspace \
  --api-url https://app.harness.io \
  --token your-api-token \
  --account your-account-id
The log service token retrieval failed. This can happen if:
  • Your authentication token has expired
  • You don’t have permission to access log service
  • There’s a network connectivity issue
Try:
hc auth login
hc iacm plan --workspace-id my-workspace
The pipeline didn’t start within the expected time. Possible causes:
  • Harness is experiencing high load
  • Pipeline is queued behind other executions
  • Pipeline configuration has errors
Check the pipeline execution URL provided in the output to see the status in Harness UI.
If logs aren’t appearing:
  1. Check the pipeline execution URL in Harness UI to verify it’s running
  2. Verify your network allows SSE connections
  3. Try running with --verbose to see detailed connection info
  4. Check if your firewall blocks the log service endpoint

​
Exit Codes

  • 0 - Plan completed successfully
  • 1 - Error occurred (authentication, network, API error, etc.)
The exit code reflects whether the CLI operation succeeded, not whether Terraform found changes. Check the plan output and pipeline execution URL for Terraform results.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us