CLI Commands

Complete reference for all StackSolo CLI commands.

Installation

# Use directly with npx (recommended)
npx stacksolo <command>

# Or install globally
npm install -g stacksolo

Command Overview

Command	Description
`stacksolo init`	Initialize a new project
`stacksolo clone`	Bootstrap from an existing project
`stacksolo scaffold`	Generate local dev files
`stacksolo add`	Add template resources to existing project
`stacksolo deploy`	Deploy infrastructure
`stacksolo destroy`	Destroy all resources
`stacksolo merge`	Merge multiple projects into one
`stacksolo status`	Show deployment status
`stacksolo events`	View deploy event logs
`stacksolo inventory`	Scan and manage GCP resources
`stacksolo refresh`	Reconcile Terraform state with GCP
`stacksolo dev`	Start local development
`stacksolo logs`	View deployment logs
`stacksolo output`	Show resource outputs

Project Commands

`stacksolo init`

Initialize a new StackSolo project.

stacksolo init [options]

Options:

Option	Description
`-n, --name <name>`	Project name
`--project-id <id>`	GCP project ID
`-r, --region <region>`	Region
`-t, --template <template>`	Project template (function-api, ui-api, etc.)
`-y, --yes`	Skip prompts and use defaults
`--create-project`	Create a new GCP + Firebase project
`--list-templates`	List available remote templates
`--skip-org-policy`	Skip org policy check and fix
`--skip-apis`	Skip enabling GCP APIs

What it does:

Checks gcloud authentication
Lists your GCP projects
Enables required APIs
Asks what type of app you’re building
Generates .stacksolo/stacksolo.config.json

Create Project Mode (`--create-project`)

Create a brand new GCP project with Firebase pre-configured:

stacksolo init --create-project

This interactive flow:

Checks gcloud and firebase CLI authentication
Prompts for project name and auto-generates a unique GCP project ID
Creates the GCP project
Guides you through enabling billing (with automatic linking if you have billing accounts)
Enables all required GCP APIs
Adds Firebase to the project
Optionally configures Firebase Authentication (pauses for manual setup)
Sets up org policies and Cloud Build permissions
Generates your stacksolo config with kernel support

Example:

# Create new project interactively
stacksolo init --create-project

# Create with pre-set name and region
stacksolo init --create-project --name my-app --region us-central1

Why use this? Each stacksolo project gets its own isolated GCP/Firebase project. This avoids cross-project complexity and keeps billing/quotas separate.

`stacksolo clone`

Clone a remote stack or bootstrap from an existing local project. Stacks are complete, deployable applications with full source code.

stacksolo clone [source] [destination] [options]

Arguments:

Argument	Description
`source`	Stack ID (e.g., `rag-platform`) or path to local project
`destination`	Directory name for the new project

Options:

Option	Description
`--list`	List available remote stacks
`-n, --name <name>`	Name for the new project
`-o, --output <dir>`	Output directory (default: current directory)
`--no-vpc`	Do not share the VPC (local clone only)
`--no-buckets`	Do not share storage buckets (local clone only)
`--no-registry`	Do not share artifact registry (local clone only)
`-y, --yes`	Skip prompts and use defaults

Examples:

# List available stacks
stacksolo clone --list

# Clone a remote stack
stacksolo clone rag-platform my-chatbot

# Clone with defaults (no prompts)
stacksolo clone rag-platform my-chatbot -y

# Clone a local project
stacksolo clone ./my-existing-project --name my-new-api

# Clone but create a new VPC (local clone only)
stacksolo clone ./my-existing-project --name my-new-api --no-vpc

Remote Stacks:

Remote stacks are hosted in the stacksolo-architectures repository. They include:

Full source code (services, apps)
Infrastructure configuration
Documentation and setup guides
Variable substitution for customization

Local Project Cloning:

When cloning a local project, shared resources (VPC, buckets, registry) are automatically configured with existing: true:

VPC Network - Reuses the source project’s VPC (avoids quota limits)
Storage Buckets - References existing buckets
Artifact Registry - Uses the same container registry

See also: Resource Sharing Guide

`stacksolo scaffold`

Generate local development files from your config.

stacksolo scaffold [options]

Option	Description
`--env-only`	Only generate .env files
`--docker-only`	Only generate docker-compose.yml
`--force`	Overwrite existing files
`--dry-run`	Show what would be generated

`stacksolo add`

Add template resources to an existing StackSolo project without re-initializing.

stacksolo add <template> [options]

Arguments:

Argument	Description
`template`	Template ID to add (e.g., `pdf-extractor`)

Options:

Option	Description
`--name <prefix>`	Prefix for added resource names (avoids conflicts)
`--dry-run`	Preview changes without applying
`--list`	List available templates
`-y, --yes`	Skip confirmation prompts

What it does:

Loads your existing stacksolo.config.json
Fetches the template configuration from the remote repository
Merges template resources (buckets, functions, etc.) into your config
Copies source files to the appropriate directories
Detects and warns about naming conflicts

Examples:

# List available templates
stacksolo add --list

# Add PDF extractor to your project
stacksolo add pdf-extractor

# Add with a name prefix (creates "docs-uploads", "docs-processed", etc.)
stacksolo add pdf-extractor --name docs

# Preview changes without applying
stacksolo add pdf-extractor --dry-run

# Add without confirmation prompts
stacksolo add pdf-extractor -y

Using Name Prefix:

When adding a template to a project that already has resources with similar names, use --name to prefix all added resources:

# First PDF processor for invoices
stacksolo add pdf-extractor --name invoice

# Second PDF processor for contracts
stacksolo add pdf-extractor --name contract

This creates separate buckets and functions for each use case:

invoice-uploads, invoice-processed, invoice-pdf-processor
contract-uploads, contract-processed, contract-pdf-processor

See also: Templates

Infrastructure Commands

`stacksolo deploy`

Deploy your infrastructure to GCP.

stacksolo deploy [options]

Option	Description
`--preview`	Show what would change
`--skip-build`	Skip building container images
`--skip-secrets`	Skip secret validation and auto-creation
`--skip-preflight`	Skip pre-flight conflict detection
`--tag <tag>`	Container image tag (default: `latest`)
`--refresh`	Refresh Terraform state first
`--force`	Force recreate conflicting resources
`--import-conflicts`	Automatically import conflicting resources
`--delete-conflicts`	Automatically delete conflicting resources
`-v, --verbose`	Show real-time Terraform and Docker output
`--helm`	Generate Helm chart (Kubernetes backend only)
`-y, --yes`	Skip confirmation prompts

Secret Auto-Creation:

When your config references secrets using @secret/secret-name in environment variables, the deploy command automatically:

Scans your config for all @secret/ references
Checks which secrets exist in GCP Secret Manager
For missing secrets:
- Checks .env.production for matching values
- Prompts you to confirm using values from .env.production
- Or prompts you to enter values manually

$ stacksolo deploy

Checking secrets...
✓ SECRET_API_KEY exists
✗ OPENAI_API_KEY missing

Found OPENAI_API_KEY in .env.production
? Use this value? (Y/n)

Creating secret 'openai-api-key'...
✓ Secret created

Deploying...

To skip secret checking: stacksolo deploy --skip-secrets

See also: Secrets Guide

Helm Output:

For Kubernetes backend projects, use --helm to generate a Helm chart instead of raw manifests:

# Preview Helm chart
stacksolo deploy --helm --preview

# Generate and deploy via Helm
stacksolo deploy --helm

The chart is generated to .stacksolo/helm-chart/. See Helm Plugin for multi-environment deployment workflows.

`stacksolo destroy`

Destroy all deployed resources.

stacksolo destroy [options]

Option	Description
`--force`	Skip confirmation prompt

`stacksolo status`

Show deployment status.

stacksolo status

`stacksolo output`

Show outputs from deployed resources.

stacksolo output [resource]

`stacksolo logs`

View deployment logs.

stacksolo logs [options]

Option	Description
`--follow`	Stream logs in real-time
`--since <duration>`	Show logs since (e.g., `1h`, `30m`)

`stacksolo events`

View high-resolution event logs for deploy operations. Events are stored in ~/.stacksolo/registry.db and provide full observability of every operation during deployment.

# View latest session events
stacksolo events

# List all sessions
stacksolo events list [options]

# View specific session
stacksolo events show [session-id] [options]

`stacksolo events` (default)

Shows events from the most recent deploy session in an ASCII table.

+--------------+-----------------+------------+----------------------+-------------------------------------+
| TIME         | PROJECT         | CATEGORY   | EVENT                | DETAILS                             |
+--------------+-----------------+------------+----------------------+-------------------------------------+
| 19:55:54.294 | my-app          | internal   | session_start        | deploy                              |
| 19:55:54.297 | my-app          | internal   | phase_start          | phase=preflight                     |
| 19:56:24.356 | my-app          | internal   | phase_end            | phase=preflight                     |
| 19:56:24.358 | my-app          | internal   | phase_start          | phase=apply                         |
| 19:56:24.359 | my-app          | terraform  | apply_start          |                                     |
| 19:57:14.519 | my-app          | terraform  | apply_end            | exit=0                              |
| 19:57:14.521 | my-app          | internal   | phase_end            | phase=apply                         |
| 19:57:14.521 | my-app          | internal   | session_end          | exit=0                              |
+--------------+-----------------+------------+----------------------+-------------------------------------+

`stacksolo events list`

List recent deploy sessions.

Option	Description
`-n, --limit <number>`	Number of sessions to show (default: 10)
`--json`	Output as JSON

`stacksolo events show`

Show events for a specific session.

# View by session ID (first 8 chars work)
stacksolo events show abc12345

# Filter by category
stacksolo events show --category terraform

# Filter by resource
stacksolo events show --resource my-bucket

# JSON output
stacksolo events show --json

Option	Description
`-c, --category <category>`	Filter by category: `internal`, `terraform`, `docker`, `gcloud`, `file`, `gcs`
`-r, --resource <name>`	Filter by resource name
`-n, --limit <number>`	Maximum events to show
`--json`	Output as JSON

Event Categories

Category	Description
`internal`	Session lifecycle, phase transitions, conflicts, user prompts
`terraform`	Terraform init, plan, apply operations and resource changes
`docker`	Docker build and push operations
`gcloud`	gcloud CLI commands
`file`	File system operations
`gcs`	GCS uploads

`stacksolo merge`

Merge multiple StackSolo projects into a single deployable stack. Useful for CI pipelines or combining microservices.

stacksolo merge <projects...> --name <name> [options]

Arguments:

Argument	Description
`projects`	Paths to project directories or config files (1 or more)

Options:

Option	Description
`--name <name>`	Name for the merged project (required)
`-o, --output <dir>`	Output directory (default: `.stacksolo-merged/`)
`--shared-vpc <name>`	Use a shared VPC for all projects
`--dry-run`	Show what would be merged without writing files

Examples:

# Merge two projects
stacksolo merge ./users-api ./orders-api --name platform

# Merge with custom output directory
stacksolo merge ./api ./web --name my-app --output ./deploy

# Preview merge without writing files
stacksolo merge ./services/* --name prod-stack --dry-run

How it works:

Loads and validates all source project configs
Detects conflicts (all projects must use the same GCP project ID)
Prefixes all resource names with source project name (e.g., api → users-api-api)
Merges networks into a single shared VPC
Combines load balancer routes with path prefixes (e.g., /users/*, /orders/*)
Writes merged config to output directory

See also: Resource Sharing Guide

`stacksolo inventory`

Scan and manage GCP resources across your projects. Helps track shared resources and find orphaned infrastructure.

stacksolo inventory [options]

Options:

Option	Description
`--project <id>`	GCP project ID to scan
`--json`	Output as JSON
`--orphaned`	Show only orphaned resources

Subcommands:

# Scan for all StackSolo resources
stacksolo inventory --project=my-gcp-project

# Adopt an unmanaged resource
stacksolo inventory adopt "VPC Network" default my-project-name

# Mark a resource as shared with other projects
stacksolo inventory share "VPC Network" my-vpc second-project third-project

Resource categories:

Managed - Resources with StackSolo labels linked to registered projects
Orphaned - StackSolo resources whose projects are no longer registered
Unmanaged - GCP resources without StackSolo labels

See also: Resource Sharing Guide

`stacksolo refresh`

Reconcile Terraform state with actual GCP resources. Use this when state becomes out of sync after failed deploys, manual deletions, or imports from another environment.

stacksolo refresh [options]

Options:

Option	Description
`--dry-run`	Preview changes without applying
`-y, --yes`	Skip confirmation prompts

What it does:

Scans GCP for resources matching your project’s naming pattern
Reads Terraform state from .stacksolo/cdktf/cdktf.out/stacks/main/terraform.tfstate
Finds drift by comparing GCP resources with state:
- Resources in GCP but not in state → need import
- Resources in state but not in GCP → need removal
Applies fixes by running terraform import and terraform state rm

Examples:

# Preview what would change
stacksolo refresh --dry-run

# Apply changes with confirmation
stacksolo refresh

# Apply changes without prompts
stacksolo refresh -y

Example output:

  Refresh Plan:

  Resources to import (exist in GCP, not in state):
    + storage: my-app-uploads
    + cloudfunctions: my-app-processor

  Resources to remove from state (in state, not in GCP):
    - google_storage_bucket.my-app-old-bucket

? Apply 2 imports and 1 removals? (Y/n)

When to use:

Scenario	Solution
Deploy failed partway, some resources created	`stacksolo refresh` then `stacksolo deploy`
Manually deleted a resource in GCP Console	`stacksolo refresh` to remove from state
Imported project from different machine	`stacksolo refresh` to sync state
”Resource already exists” errors	`stacksolo refresh --dry-run` to see drift

See also: Deployment Troubleshooting

Development Commands

`stacksolo dev`

Start a local development environment.

stacksolo dev [options]

Option	Description
`--local`	Run services locally without Docker/K8s
`--stop`	Tear down local environment
`--status`	Show running pods
`--logs [service]`	Tail logs
`--rebuild`	Force regenerate K8s manifests
`--no-emulators`	Skip Firebase/Pub/Sub emulators

Local Mode (`--local`)

Run services directly on your machine without Docker or Kubernetes.

stacksolo dev --local
stacksolo dev --local --no-emulators

How it works:

Reads config from .stacksolo/stacksolo.config.json
Finds all services (functions, UIs, containers)
Runs npm run dev for each service in parallel
Streams logs with colored prefixes per service
Ctrl+C gracefully stops all processes

Port allocation:

Service Type	Ports
Functions	8081, 8082, 8083…
UIs	3000, 3001, 3002…
Containers	9000, 9001, 9002…

Requirements:

All services must have an npm run dev script in their package.json:

Service Type	Required `dev` Script
Function	`tsup src/index.ts --watch --onSuccess 'functions-framework ...'`
UI (React/Vue)	`vite`
Container	`tsx watch src/index.ts`

The CLI injects PORT env var for functions/containers, and passes --port flag for UIs.

Kubernetes Mode (default)

Start a local Kubernetes environment via OrbStack or Docker Desktop.

stacksolo dev

Prerequisites: OrbStack or any local Kubernetes cluster.

`stacksolo build`

Build container images locally.

stacksolo build [options]

Option	Description
`--service <name>`	Build specific service
`--tag <tag>`	Image tag
`--push`	Push to registry

Configuration Commands

`stacksolo config`

Manage configuration.

# View config
stacksolo config show

# Edit config
stacksolo config edit

# Validate config
stacksolo config validate

`stacksolo env`

Manage environment variables.

# List env vars
stacksolo env list

# Set env var
stacksolo env set API_KEY=secret123

# Remove env var
stacksolo env unset API_KEY

Global Options

Option	Description
`--help`	Show help
`--version`	Show version
`--verbose`	Detailed output
`--quiet`	Suppress output

Environment Variables

Variable	Description
`STACKSOLO_CONFIG`	Path to config file
`STACKSOLO_PROJECT`	GCP project ID override
`STACKSOLO_REGION`	Region override
`GOOGLE_APPLICATION_CREDENTIALS`	Path to service account key

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Authentication error
4	Deployment error

Common Workflows

First-time setup

npm install -g @stacksolo/cli
gcloud auth login
gcloud auth application-default login
mkdir my-app && cd my-app
stacksolo init

Daily development

# Local mode (no Docker/K8s - fastest)
stacksolo dev --local
# Make changes, see live reload...
# Ctrl+C to stop

# Or Kubernetes mode
stacksolo dev
stacksolo dev --logs api
stacksolo dev --stop

Deploying changes

stacksolo deploy --preview
stacksolo deploy
stacksolo status

CLI Commands

Installation

Command Overview

Project Commands

stacksolo init

Create Project Mode (--create-project)

stacksolo clone

stacksolo scaffold

stacksolo add

Infrastructure Commands

stacksolo deploy

stacksolo destroy

stacksolo status

stacksolo output

stacksolo logs

stacksolo events

stacksolo events (default)

stacksolo events list

stacksolo events show

Event Categories

stacksolo merge

stacksolo inventory

stacksolo refresh

Development Commands

stacksolo dev

Local Mode (--local)

Kubernetes Mode (default)

stacksolo build

Configuration Commands

stacksolo config

stacksolo env

Global Options

Environment Variables

Exit Codes

Common Workflows

First-time setup

Daily development

Deploying changes

`stacksolo init`

Create Project Mode (`--create-project`)

`stacksolo clone`

`stacksolo scaffold`

`stacksolo add`

`stacksolo deploy`

`stacksolo destroy`

`stacksolo status`

`stacksolo output`

`stacksolo logs`

`stacksolo events`

`stacksolo events` (default)

`stacksolo events list`

`stacksolo events show`

`stacksolo merge`

`stacksolo inventory`

`stacksolo refresh`

`stacksolo dev`

Local Mode (`--local`)

`stacksolo build`

`stacksolo config`

`stacksolo env`