CLI Commands - Amazon Nova Act

Command Overview

The Nova Act CLI provides seven core workflow management commands:

Command	Description
`create`	Register a new workflow in configuration
`deploy`	Build and deploy workflow to AWS AgentCore
`run`	Execute deployed workflow with payload
`list`	Show all configured workflows
`show`	Display detailed workflow information
`update`	Modify workflow configuration
`delete`	Remove workflow from configuration

create

Syntax

act workflow create --name <workflow-name> [OPTIONS]

Options

Option	Required	Description
`--name, -n`	Yes	Name of the workflow
`--workflow-definition-arn`	No	Optional WorkflowDefinition ARN to associate
`--region`	No	Region for WorkflowDefinition (defaults to config default_region)
`--s3-bucket-name`	No	Custom S3 bucket name for workflow exports
`--skip-s3-creation`	No	Skip automatic S3 bucket creation

Examples

Basic Creation
With Existing WorkflowDefinition
Custom S3 Bucket
Skip S3 Creation

Create a workflow with default settings:

act workflow create --name my-workflow

Output:

✅ Created workflow 'my-workflow'
   Region: us-east-1
   WorkflowDefinition ARN: arn:aws:nova-act:us-east-1:123456789012:workflow-definition/my-workflow
   Console URL: https://console.aws.amazon.com/nova-act/...
   State saved to: ~/.act_cli/state/123456789012/us-east-1/workflows.json

Next Steps
  act workflow deploy --name my-workflow --source-dir <your-code-directory>

Associate an existing WorkflowDefinition:

act workflow create --name my-workflow \
  --workflow-definition-arn arn:aws:nova-act:us-east-1:123456789012:workflow-definition/my-workflow

Specify a custom S3 bucket:

act workflow create --name my-workflow \
  --s3-bucket-name my-custom-bucket

Create workflow without S3 bucket:

act workflow create --name my-workflow --skip-s3-creation

Notes

The command automatically creates a WorkflowDefinition with the provided name
Default S3 bucket follows pattern: nova-act-{account-id}-{region}
Workflow name must match the name in the WorkflowDefinition ARN if provided

deploy

Build and deploy a workflow to AWS AgentCore Runtime with containerization.

Syntax

act workflow deploy [--name <workflow-name>] [--source-dir <path>] [OPTIONS]

Options

Option	Required	Description
`--name, -n`	No	Name of the workflow (auto-generated if using `--source-dir`)
`--source-dir`	No*	Path to source directory for quick-deploy
`--entry-point`	No	Entry point script file (e.g., `my_script.py`, defaults to `main.py`)
`--region`	No	AWS region for deployment
`--execution-role-arn`	No	Use existing IAM role ARN for workflow execution
`--ecr-repo`	No	Custom ECR repository URI
`--no-build`	No	Skip building before deploy
`--skip-entrypoint-validation`	No	Skip entry point validation (advanced users)
`--build-dir`	No	Custom local directory for build files
`--overwrite-build-dir`	No	Overwrite existing build directory without prompting
`--s3-bucket-name`	No	Custom S3 bucket name for workflow exports
`--skip-s3-creation`	No	Skip automatic S3 bucket creation

Either --name (for named workflows) or --source-dir (for quick-deploy) must be provided.

Examples

Deploy a directory without pre-creating a workflow:

act workflow deploy --source-dir /path/to/your/project

Output:

🚀 Deployment successful!

Deployment Details:
  Name:       workflow-20251130-120945
  Agent ARN:  arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/abc123
  Region:     us-east-1
  Workflow Console: https://console.aws.amazon.com/nova-act/...
  Agent Console:    https://console.aws.amazon.com/bedrock/agentcore/...

Next Steps:
  Run workflow:
    act workflow run --name workflow-20251130-120945 --payload "{}"
  Run with logs:
    act workflow run --name workflow-20251130-120945 --payload "{}" --tail-logs

Deploy a pre-created workflow:

act workflow deploy --name my-workflow --source-dir /path/to/code

Specify a custom entry point:

act workflow deploy --source-dir /path/to/project --entry-point app.py

The entry point must contain a def main(payload): function.

Use an existing execution role:

act workflow deploy --source-dir /path/to/code \
  --execution-role-arn arn:aws:iam::123456789012:role/my-execution-role

Preserve build artifacts in a specific location:

act workflow deploy --source-dir /path/to/code \
  --build-dir /tmp/my-build \
  --overwrite-build-dir

Deploy to a custom ECR repository:

act workflow deploy --source-dir /path/to/code \
  --ecr-repo 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo

Deployment Process

The deploy command performs these steps automatically:

Validate Entry Point

Checks that the entry point exists and contains a main(payload) function.

Build Docker Image

Creates a container image with your workflow code and dependencies.

Push to ECR

Authenticates with ECR and pushes the Docker image.

Create/Update IAM Role

Creates an execution role with necessary permissions (unless --execution-role-arn provided).

Create WorkflowDefinition

Registers the workflow with the Nova Act service.

Deploy to AgentCore

Creates or updates the AgentCore Runtime with the new image.

Notes

Default build location: ~/.act_cli/builds/{workflow-name}/
Build artifacts are persistent and not automatically cleaned up
Default builds always overwrite previous builds for the same workflow
Custom build directories require --overwrite-build-dir flag to overwrite

run

Execute a deployed workflow on AgentCore Runtime with a JSON payload.

Syntax

act workflow run --name <workflow-name> (--payload <json> | --payload-file <path>) [OPTIONS]

Options

Option	Required	Description
`--name, -n`	Yes	Name of the workflow
`--payload`	No*	JSON payload string
`--payload-file`	No*	Path to JSON payload file
`--region`	No	AWS region for deployment
`--tail-logs`	No	Stream logs in real-time (requires `logs:StartLiveTail` permission)
`--timeout`	No	Read timeout in seconds (default: 7200)

Either --payload or --payload-file must be provided.

Examples

Basic Execution
With Payload File
With Log Streaming
With Environment Variables
With Custom Timeout

Run with inline JSON payload:

act workflow run --name my-workflow --payload '{"input": "test data"}'

Output:

Workflow Details
Workflow: my-workflow
Agent ARN: arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/abc123
Region: us-east-1

Logging Information
Runtime logs: /aws/bedrock-agentcore/runtimes/abc123-default
OTEL logs: /aws/bedrock-agentcore/runtimes/abc123-default/runtime-logs

Tail logs with AWS CLI v2:
  aws logs tail /aws/bedrock-agentcore/runtimes/abc123-default --follow
  aws logs tail /aws/bedrock-agentcore/runtimes/abc123-default --since 1h

Execution Status
Starting workflow execution...
⚠ Initial startup may take a few moments
✅ Workflow execution completed successfully!
🔗 View in console: https://console.aws.amazon.com/nova-act/...

Run with JSON file:

act workflow run --name my-workflow --payload-file payload.json

Where payload.json contains:

{
  "input": "data",
  "options": {
    "timeout": 300
  }
}

Stream logs during execution:

act workflow run --name my-workflow \
  --payload '{"input": "test"}' \
  --tail-logs

Output includes real-time logs:

📋 Log tailing enabled - showing logs from /aws/bedrock-agentcore/runtimes/abc123-default
────────────────────────────────────────────────────────────
12:34:56 Starting workflow execution
12:34:57 Loading browser automation
12:34:58 Navigating to target URL
12:35:01 Workflow completed
────────────────────────────────────────────────────────────
✅ Workflow execution completed successfully!

Pass environment variables to the workflow:

act workflow run --name my-workflow --payload '{
  "AC_HANDLER_ENV": {
    "NOVA_ACT_API_KEY": "your-api-key-here",
    "DEBUG": "true"
  },
  "input": "data"
}'

These variables are available in your workflow via os.environ.

Increase timeout for long-running workflows:

act workflow run --name my-workflow \
  --payload '{}' \
  --timeout 14400

Default timeout is 7200 seconds (2 hours).

Log Sources

When using --tail-logs, the CLI streams from:

Application logs: stdout/stderr from your workflow
OpenTelemetry logs: Tracing and instrumentation data

Notes

Log streaming continues until workflow completes or you press Ctrl+C
Ctrl+C stops tailing but doesn’t terminate the workflow
Initial startup may take 30-60 seconds for cold starts

list

Show all configured workflows in the current region.

Syntax

act workflow list [OPTIONS]

Options

Option	Required	Description
`--region`	No	AWS region to query

Examples

List All Workflows
List in Specific Region
No Workflows

Show workflows in default region:

act workflow list

Output:

Workflows in us-east-1

my-workflow (2024-11-30)
test-workflow (2024-11-29)
workflow-20251130-120945 (2024-11-30)

Use act workflow show -n <name> for detailed information.

Show workflows in a specific region:

act workflow list --region us-west-2

When no workflows exist:

act workflow list

Output:

No workflows found. Use act workflow create to create your first workflow.

Notes

State is isolated per region and AWS account
Use show command for detailed information about a specific workflow

show

Display detailed information about a specific workflow.

Syntax

act workflow show --name <workflow-name> [OPTIONS]

Options

Option	Required	Description
`--name, -n`	Yes	Name of the workflow to show
`--region`	No	AWS region to query

Examples

Show Workflow Details
Show in Specific Region
Workflow Not Found

Display full workflow information:

act workflow show --name my-workflow

Output:

Workflow Details
Name: my-workflow
Directory: /path/to/source/code
Created: 2024-11-30 12:51:39
Workflow Definition ARN: arn:aws:nova-act:us-east-1:123456789012:workflow-definition/my-workflow
Console URL: https://console.aws.amazon.com/nova-act/...
AgentCore Deployment: arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/abc123
Container Image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/nova-act-cli-default:my-workflow-20241130-125139

Query a different region:

act workflow show --name my-workflow --region us-west-2

When workflow doesn’t exist:

act workflow show --name nonexistent

Output:

Workflow 'nonexistent' not found. Use act workflow list to see available workflows.

Notes

Shows directory path even if it no longer exists on disk
Provides direct links to AWS Console for WorkflowDefinition and AgentCore Runtime

update

Update an existing workflow’s WorkflowDefinition ARN.

Syntax

act workflow update --name <workflow-name> --workflow-definition-arn <arn> [OPTIONS]

Options

Option	Required	Description
`--name, -n`	Yes	Name of the workflow to update
`--workflow-definition-arn`	Yes	New WorkflowDefinition ARN to associate
`--region`	No	Region for WorkflowDefinition (defaults to config default_region)

Examples

Update WorkflowDefinition
Update in Specific Region

Associate a new WorkflowDefinition ARN:

act workflow update --name my-workflow \
  --workflow-definition-arn arn:aws:nova-act:us-east-1:123456789012:workflow-definition/my-workflow

Output:

Updated workflow 'my-workflow' WorkflowDefinition ARN in region 'us-east-1':
  Old: Not set
  New: arn:aws:nova-act:us-east-1:123456789012:workflow-definition/my-workflow
  Console URL: https://console.aws.amazon.com/nova-act/...

✅ Workflow 'my-workflow' updated successfully!
Use act workflow show --name my-workflow for full details.

Update workflow in a different region:

act workflow update --name my-workflow \
  --workflow-definition-arn arn:aws:nova-act:us-west-2:123456789012:workflow-definition/my-workflow \
  --region us-west-2

Notes

Workflow name must match the name in the WorkflowDefinition ARN
The CLI validates ARN format automatically
To change source directory or entry point, use deploy command

delete

Remove a workflow from local configuration.

Syntax

act workflow delete --name <workflow-name> [OPTIONS]

Options

Option	Required	Description
`--name, -n`	Yes	Name of the workflow to delete
`--region`	No	AWS region (defaults to configured region)
`--force`	No	Skip confirmation prompt

Examples

Delete Workflow
Force Delete
Delete in Specific Region

Remove a workflow with confirmation:

act workflow delete --name my-workflow

Output:

Workflow to delete: my-workflow
Target region: us-east-1
Action: Remove from configuration
Are you sure you want to proceed? [y/N]: y
✅ Removed 'my-workflow' from configuration

Skip confirmation prompt:

act workflow delete --name my-workflow --force

Output:

Workflow to delete: my-workflow
Target region: us-east-1
Action: Remove from configuration
✅ Removed 'my-workflow' from configuration

Remove workflow from a specific region:

act workflow delete --name my-workflow --region us-west-2

Important Notes

AWS Resources Are NOT DeletedThe delete command only removes the workflow from local CLI configuration. It does NOT delete:

AgentCore Runtime
WorkflowDefinition
ECR images
IAM roles
S3 buckets
CloudWatch Logs

You must manually clean up these AWS resources if needed.

Global Options

These options apply to all workflow commands:

Option	Description
`--profile <name>`	Use specific AWS profile from `~/.aws/credentials`
`--help`	Show command help

Using AWS Profiles

# Deploy with specific profile
act workflow --profile development deploy --name my-workflow --source-dir /path/to/code

# Run with specific profile
act workflow --profile production run --name my-workflow --payload '{}'

The --profile option must come before the subcommand (deploy, run, etc.).

Command Cheat Sheet

# Create and deploy named workflow
act workflow create --name my-workflow
act workflow deploy --name my-workflow --source-dir ./code
act workflow run --name my-workflow --payload '{}'

# Quick deploy without pre-creation
act workflow deploy --source-dir ./code
act workflow run --name workflow-20251130-120945 --payload '{}'

# Manage workflows
act workflow list
act workflow show --name my-workflow
act workflow update --name my-workflow --workflow-definition-arn <arn>
act workflow delete --name my-workflow

# Deploy with custom options
act workflow deploy --name my-workflow \
  --source-dir ./code \
  --entry-point app.py \
  --execution-role-arn <arn> \
  --region us-east-1

# Run with log streaming
act workflow run --name my-workflow \
  --payload-file payload.json \
  --tail-logs \
  --timeout 14400

CLI Reference

​Command Overview

​create

​Syntax

​Options

​Examples

​Notes

​deploy

​Syntax

​Options

​Examples

​Deployment Process

​Notes

​run

​Syntax

​Options

​Examples

​Log Sources

​Notes

​list

​Syntax

​Options

​Examples

​Notes

​show

​Syntax

​Options

​Examples

​Notes

​update

​Syntax

​Options

​Examples

​Notes

​delete

​Syntax

​Options

​Examples

​Important Notes

​Global Options

​Using AWS Profiles

​Command Cheat Sheet

Build docs developers (and LLMs) love

Command Overview

create

Syntax

Options

Examples

Notes

deploy

Syntax

Options

Examples

Deployment Process

Notes

run

Syntax

Options

Examples

Log Sources

Notes

list

Syntax

Options

Examples

Notes

show

Syntax

Options

Examples

Notes

update

Syntax

Options

Examples

Notes

delete

Syntax

Options

Examples

Important Notes

Global Options

Using AWS Profiles

Command Cheat Sheet