Installation

The Hereya CLI is your primary interface for managing AWS resources as code dependencies. Hereya lets you add AWS infrastructure to your applications as easily as npm packages, using reusable infrastructure as code components built with AWS CDK (TypeScript) or OpenTofu.

This guide walks you through installing the CLI, connecting to Hereya Cloud, and preparing your AWS environment.

Prerequisites

Before installing Hereya, ensure you have:

Node.js 20 or higher - Hereya CLI is built on Node.js
AWS Account - Required for infrastructure management
AWS CLI configured - Needed for resource provisioning

Verify your Node.js version:

node --version
# Should output v20.0.0 or higher

If you need to install or upgrade Node.js, visit nodejs.org.

Installing Hereya CLI

Hereya CLI is available as an npm package and should be installed globally for system-wide access.

npm install -g hereya-cli

yarn global add hereya-cli

pnpm add -g hereya-cli

After installation, verify it’s working:

hereya --version

Connecting to Hereya Cloud

After installation, connect to Hereya Cloud to enable full functionality:

hereya login

This command opens your browser for authentication and configures your local CLI.

Why Connect to Hereya Cloud?

Hereya Cloud provides essential services that enhance your infrastructure management:

Package Registry Access - Browse and install AWS resource packages from the Hereya registry
Project Metadata - Store and sync project configurations across team members
Workspace Management - Centrally manage different environments (dev, staging, production)
Team Collaboration - Share resources and configurations with your team
Version Control - Track package versions and updates

Your authentication credentials are stored securely on your local machine and are never transmitted with your infrastructure code.

Bootstrap AWS Infrastructure

Before creating your first Hereya project, you need to bootstrap your AWS account. This one-time setup prepares AWS to work with Hereya:

hereya bootstrap aws

What Does Bootstrap Do?

The bootstrap process creates foundational AWS resources that Hereya needs:

State Storage Bucket - Secure S3 bucket with versioning and encryption for storing OpenTofu state files (bucket name includes “terraform” for historical compatibility)
Hereya Backend Bucket - S3 bucket with object lock enabled for storing Hereya backend files and deployment artifacts
DynamoDB Table - Table named terraformStateLock for managing concurrent access to state files
CloudFormation Stack - Manages all bootstrap infrastructure components

Hereya packages are reusable infrastructure as code components that currently support:

AWS CDK (TypeScript)
OpenTofu (open-source fork of Terraform)

Security features include:

All S3 buckets have public access blocked
Encryption enforced on all buckets
SSL/TLS required for all bucket access
Versioning enabled for state tracking and rollback capabilities
Object lock on backend bucket for additional data protection

You can review the exact infrastructure code at github.com/hereya/bootstrap-aws-stack.

These resources are:

Created once per AWS account/region combination
Shared across all your Hereya projects
Managed separately from your application resources
Designed to not interfere with existing AWS resources

Important: The bootstrap command uses your current AWS CLI configuration. Ensure you’re connected to the correct AWS account and region before running it.

Verify Your Setup

After completing the installation steps, verify everything is configured correctly:

# Check CLI installation
hereya --version

Next Steps

With Hereya installed and configured, you’re ready to start building:

Quick Start Guide - Build your first app with AWS resources in minutes
First Project - Detailed walkthrough of project setup
Browse Package Registry - Explore available AWS resource packages
Managing Dependencies - Learn how to add and configure AWS resources

Troubleshooting

Node.js Version Error

If you see an error about Node.js version:

# Check your current version
node --version

# If below v20, upgrade Node.js from nodejs.org
# Or use a version manager like nvm:
nvm install 20
nvm use 20

Permission Errors During Installation

If you encounter permission errors with global installation:

Option 1: Fix npm permissions (Recommended)

# Configure npm to use a different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Option 2: Use a Node version manager

nvm for macOS/Linux
nvm-windows for Windows

AWS Credentials Not Found

If bootstrap fails with credential errors:

# Configure AWS CLI
aws configure

# Or set environment variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1

Network/Proxy Issues

If you’re behind a corporate proxy:

# Set proxy for npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Set proxy for AWS CLI
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

Updating Hereya CLI

Keep your Hereya CLI up to date for the latest features and fixes:

Check Current Version

hereya --version

Update Commands

npm update -g hereya-cli

yarn global upgrade hereya-cli

pnpm update -g hereya-cli

View Available Versions

npm view hereya-cli versions --json

Uninstalling Hereya

Remove Bootstrap Resources (Optional)

Before uninstalling the CLI, you can optionally remove the bootstrap infrastructure:

hereya unbootstrap aws

Note: This command removes the CloudFormation stack but does not delete the S3 buckets to prevent accidental loss of state files. You’ll need to manually delete the buckets using AWS CLI or Console after ensuring no active projects depend on them.

Remove Hereya CLI

npm uninstall -g hereya-cli

yarn global remove hereya-cli

pnpm remove -g hereya-cli