@schematichq/taskonaut
Advanced tools
Interactive CLI tool for exec into AWS ECS tasks (containers), rollback services to previous task definition revisions, and clean up unused task definitions - from [SchematicHQ](https://schematichq.com)
░██████╗░█████╗░██╗░░██╗███████╗███╗░░░███╗░█████╗░████████╗██╗░█████╗░
██╔════╝██╔══██╗██║░░██║██╔════╝████╗░████║██╔══██╗╚══██╔══╝██║██╔══██╗
╚█████╗░██║░░╚═╝███████║█████╗░░██╔████╔██║███████║░░░██║░░░██║██║░░╚═╝
░╚═══██╗██║░░██╗██╔══██║██╔══╝░░██║╚██╔╝██║██╔══██║░░░██║░░░██║██║░░██╗
██████╔╝╚█████╔╝██║░░██║███████╗██║░╚═╝░██║██║░░██║░░░██║░░░██║╚█████╔╝
╚═════╝░░╚════╝░╚═╝░░╚═╝╚══════╝╚═╝░░░░░╚═╝╚═╝░░╚═╝░░░╚═╝░░░╚═╝░╚════╝░
Interactive CLI tool for exec into AWS ECS tasks (containers), rollback services to previous task definition revisions, and clean up unused task definitions - from SchematicHQ
taskonautis a combination of "Task" (ECS tasks) and "Astronaut" We followed Command Line Interface Guidelines, An open-source guide to help you write better command-line programs, taking traditional UNIX principles and updating them for the modern day.
[!WARNING] Make sure you have met the Amazon ECS Exec prerequisites.
npm install -g @schematichq/taskonaut
For development or if you prefer to install from source:
# Clone the repository
git clone https://github.com/SchematicHQ/taskonaut.git
cd taskonaut
# Install dependencies and install globally from source
npm install
npm install -g .
After installation, you can use taskonaut command globally just like the npm package installation.
Note: The global npm installation method is recommended for most users as it provides automatic updates and easier management.
# Configure AWS profile and region
taskonaut config set
# Show current configuration
taskonaut config show
# Clear configuration
taskonaut config cleanup
# Run diagnostics to check environment setup
taskonaut doctor
# Rollback ECS service to previous revision
taskonaut rollback
# Clean up unused task definition revisions
taskonaut prune
# Start interactive session
taskonaut
Usage: taskonaut [options] [command]
✨ Interactive ECS task executor, rollback tool, and task definition cleanup utility
Options:
-h, --help display help for command
Commands:
config Manage configuration settings
doctor Run diagnostics to check your environment setup
rollback Rollback an ECS service to a previous task definition revision
prune Clean up unused task definition revisions
Configuration is stored in:
~/Users/$USER/Library/Preferences/taskonaut-nodejs~/.config/taskonaut-nodejs%APPDATA%\taskonaut-nodejsThe rollback feature allows you to safely revert ECS services to previous task definition revisions with an interactive, step-by-step process.
taskonaut uses AWS ECS's native rollback capability by calling updateService with a previous task definition ARN. This is the same mechanism used by:
aws ecs update-service --task-definition previous-revision# Interactive rollback with step-by-step guidance
taskonaut rollback
# Example flow:
# 1. Select cluster: production-cluster
# 2. Select service: api-service (revision 245 → rollback available)
# 3. Choose target: Revision 243 (created 2 hours ago)
# 4. Review changes: image tags, CPU/memory differences
# 5. Confirm: "Proceed with rollback? (245 → 243)"
# 6. Execute: Rollback initiated with deployment tracking
[!IMPORTANT] Task Definition Retention: To enable rollback functionality, your infrastructure should retain old task definition revisions. If using Pulumi, Terraform, or similar IaC tools, configure:
Pulumi:
const taskDefinition = new aws.ecs.TaskDefinition("my-task", {
// ... other configuration
skipDestroy: true, // Retains old revisions when updating
});
Terraform:
resource "aws_ecs_task_definition" "my_task" {
# ... other configuration
skip_destroy = true
lifecycle {
create_before_destroy = true
}
}
Why This Matters:
skipDestroy: true, old task definition revisions are deleted during updatesThe pruning feature helps you clean up unused task definition revisions to reduce clutter and manage AWS ECS resources efficiently. It provides an interactive, safe way to delete old revisions while protecting critical ones.
Taskonaut uses AWS ECS's native two-step deletion process:
Deregister (deregisterTaskDefinition): Marks a task definition as INACTIVE
Delete (deleteTaskDefinitions): Permanently removes INACTIVE task definitions
# Interactive pruning with all safety checks
taskonaut prune
# Example flow:
# 1. Select family: my-api-service
# 2. Check service usage in production-cluster? Yes
# 3. View analysis: 50 total, 2 protected, 5 keep, 43 eligible
# 4. Select revisions: (pre-checked: revisions outside latest 5)
# 5. Review dry-run: Will deregister 10, will delete 33
# 6. Type to confirm: my-api-service
# 7. Final confirmation: Yes
# 8. Execute: Deregister → Delete → Results
taskonaut prune periodically (monthly/quarterly) to prevent accumulation[!WARNING]
- Deletion is permanent: Deleted task definitions cannot be recovered
- Deregister is reversible: INACTIVE revisions can still be updated or deleted later
- Service impact: Deleting an in-use revision won't affect running services, but always check usage first
- Batch operations: Delete operations process up to 10 revisions at a time for efficiency
[!TIP]
- First time users: Start by only deleting revisions that are more than 6 months old
- Keep history: Consider keeping at least 10 revisions for rollback flexibility
- Infrastructure as Code: If using IaC tools, ensure
skipDestroy: trueis set to preserve revision history
Taskonaut is optimized for handling large revision sets with built-in rate limiting:
Automatic Rate Limiting:
For 500+ Revisions:
Best Practices for Large Sets:
If Rate Limiting Occurs:
aws sso loginaws sso login --porfile PORFILE_NAME
taskonaut
assumevault[!CAUTION] Error messages:
Task not found: Ensure the ECS task is runningContainer not found: Task may have zero containersInvalid AWS profile: Configure AWS profile firstNo clusters found: Ensure you have access to ECS clusters in the selected AWS region.No tasks found in cluster: The selected cluster has no running tasks. taskonaut will offer options to go back and select a different cluster or check your AWS Console for running tasks.AWS CLI is not installed: Install AWS CLI v2.Session Manager Plugin is not installed: Install the Session Manager Plugin.AWS initialization failed: Check your AWS credentials and network connectivity.No services found in cluster: Ensure the cluster has running services.No other revisions available for rollback: The service only has one task definition revision, or old revisions were deleted (see skipDestroy configuration above).Rollback failed: Check ECS service permissions and ensure the target task definition revision still exists.Unable to start command: Failed to start pty: fork/exec /bin/sh: no such file or directory: Container doesn't have a shell (common with minimal containers like Twingate connectors, distroless images). These containers can't be accessed via exec.No task definition families found: No task definitions exist in your AWS account/region. Ensure you have deployed at least one ECS service.No revisions available for deletion: All revisions are either protected (latest/in-use) or within the latest 5. This is normal for recently created task definitions.Failed to deregister task definition: Ensure you have ecs:DeregisterTaskDefinition IAM permission.Failed to delete task definition: Task definition must be deregistered (INACTIVE) before deletion. Ensure you have ecs:DeleteTaskDefinition IAM permission.Pruning operation partially failed: Some revisions may be in use or locked. Check the detailed error messages and try again later.AWS CLI not foundbrew install awscli
Session Manager Plugin not foundbrew install session-manager-plugin
Invalid AWS profile
Ensure your AWS profile is configured correctly. If using AWS SSO, log in with:aws sso login --profile your-profile
AWS Credentials not configured
Configure your AWS credentials by setting up your ~/.aws/credentials and ~/.aws/config files. You can use aws configure to set up access keys, or set up AWS SSO profiles.
No clusters found
Ensure you have access to ECS clusters in the selected AWS region and that your AWS credentials have the necessary permissions.
https://github.com/aws-containers/amazon-ecs-exec-checker
bash <( curl -Ls https://raw.githubusercontent.com/aws-containers/amazon-ecs-exec-checker/main/check-ecs-exec.sh ) <YOUR_ECS_CLUSTER_NAME> <YOUR_ECS_TASK_ID>
MIT
Pull requests welcome! Please read CONTRIBUTING.md for details.
We use Dependabot to keep our dependencies up to date.
We use Semantic Release to automate the release process.
We use GitHub Actions to run our tests and build our project.
aws-vaultFAQs
Interactive CLI tool for exec into AWS ECS tasks (containers), rollback services to previous task definition revisions, and clean up unused task definitions - from [SchematicHQ](https://schematichq.com)
The npm package @schematichq/taskonaut receives a total of 16 weekly downloads. As such, @schematichq/taskonaut popularity was classified as not popular.
We found that @schematichq/taskonaut demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.