Skip to main content

​
What is the Nova Act CLI?

The Nova Act CLI is a command-line tool that provides a streamlined process for deploying Python workflows to AWS AgentCore Runtime. It handles containerization, ECR management, IAM roles, S3 bucket creation, and AgentCore Runtime deployments automatically with account-based configuration management.
The Nova Act CLI is a convenience utility to quickstart the creation and deployment of remote Nova Act workflows. It SHOULD NOT be used as a dependency in production code!

​
Key Features

Quick Deploy

Deploy any Python script directly without pre-configuration

Auto-Containerization

Automatic Docker image building and management

ECR Management

Automatic repository creation and image pushing

IAM Integration

Automatic role creation and permission management

Multi-Region Support

Deploy to any AWS region with isolated state management

Workflow Tracking

Persistent configuration with file locking for concurrent access

​
How It Works

The CLI provides two primary deployment workflows: Create and manage named workflows for repeated deployments and console visibility: 
# 1. Create workflow configuration
act workflow create --name my-workflow

# 2. Deploy the workflow
act workflow deploy --name my-workflow --source-dir /path/to/project

# 3. Run the deployed workflow
act workflow run --name my-workflow --payload '{"input": "data"}'

​
Quick Deploy

Deploy any Python script directly without pre-creating a named workflow: 
# Deploy a directory with auto-detected entry point
act workflow deploy --source-dir /path/to/your/project

# Deploy with specific entry point
act workflow deploy --source-dir /path/to/project --entry-point my_script.py

# Run the deployed workflow (uses auto-generated name)
act workflow run --name workflow-20251130-120945 --payload '{"input": "test data"}'
Quick deploy creates a persistent workflow with an auto-generated name like workflow-20251130-120945. The workflow remains in your configuration and can be managed with standard workflow commands (list, show, delete, etc.).

​
When to Use the CLI

The CLI is ideal for:
  • Rapid prototyping of Nova Act workflows
  • Testing workflows in AWS AgentCore environment
  • Debugging workflow behavior in production-like conditions
  • Iterating on workflow logic with quick redeployment
Perfect for:
  • Demonstrating Nova Act capabilities
  • Building proof-of-concept applications
  • Exploring AWS AgentCore features
  • Quick experimentation with browser automation
Great for:
  • Small-scale automation tasks
  • Personal productivity workflows
  • Learning Nova Act and AWS services
  • Side projects and hackathons

​
When NOT to Use the CLI

Production deployments should use infrastructure-as-code tools like:
  • AWS CDK
  • Terraform
  • CloudFormation
  • AWS SAM
These tools provide:
  • Version control integration
  • Automated testing and validation
  • Rollback capabilities
  • Team collaboration features
  • CI/CD pipeline integration

​
AWS Resources Created

The CLI automatically provisions and manages these AWS resources:
ResourceNaming PatternDescription
ECR Repositorynova-act-cli-defaultShared across workflows
IAM Rolenova-act-{workflow-name}-roleAuto-created unless --execution-role-arn provided
S3 Bucketnova-act-{account-id}-{region}Auto-created unless --skip-s3-creation
AgentCore RuntimeCustomOne per workflow
WorkflowDefinitionCustomAuto-created via nova-act service
CloudWatch Logs/aws/bedrock-agentcore/runtimes/{agent-id}*Runtime and OTEL logs

​
Architecture

​
State Management

The CLI maintains separate state files per AWS account and region: 
~/.act_cli/
├── state/
│   ├── 123456789012/
│   │   ├── us-east-1/
│   │   │   └── workflows.json
│   │   └── us-west-2/
│   │       └── workflows.json
│   └── 987654321098/
│       └── us-east-1/
│           └── workflows.json
├── builds/
│   └── {workflow-name}/
└── config.yml

​
Next Steps

Installation

Install the CLI and configure prerequisites

Commands Reference

Learn all available CLI commands

Deployment Guide

Deploy your first workflow

Configuration

Configure profiles, regions, and environment variables

Build docs developers (and LLMs) love

Get started for freeTalk to us