Skip to content
Raindrop Developer Hub

raindrop build

Overview

The raindrop build command manages the entire lifecycle of Raindrop applications. You can initialize projects, generate code from manifests, deploy to production, and monitor application health.

This command operates on your project’s manifest file (raindrop.manifest by default). The manifest defines your application’s structure, including services, databases, handlers, and environment variables. Most commands automatically detect the manifest in your current directory.

Use raindrop build commands to move from local development to production deployment. The workflow starts with initialization, proceeds through code generation and validation, and ends with deployment and monitoring.

Basic Usage

Start a new project in the current directory:

Terminal window
raindrop build init

Generate code from your manifest:

Terminal window
raindrop build generate

Deploy your application:

Terminal window
raindrop build deploy

Check deployment status:

Terminal window
raindrop build status

Command Syntax

raindrop build COMMAND


COMMANDS
  raindrop build init [PATH]              Initialize new project
  raindrop build generate                 Generate code from manifest
  raindrop build deploy                   Deploy application to Raindrop
  raindrop build status                   Show application status
  raindrop build start                    Start deployed application
  raindrop build stop                     Stop running application
  raindrop build branch <branch>          Create new version branch
  raindrop build checkout [version]       Switch to specific version
  raindrop build delete [application]     Delete application versions
  raindrop build validate                 Run type checking and validation
  raindrop build list                     List applications in catalog
  raindrop build sandbox                  Mark version as sandboxed
  raindrop build unsandbox                Remove sandbox status
  raindrop build env set <var> [value]    Set environment variable
  raindrop build env get <var>            Get environment variable

Initialize Command

Syntax: raindrop build init [PATH]

Create a new Raindrop project with default structure.

Arguments:

  • [PATH] - Directory path (default: current directory)

Flags:

  • --overwrite - Overwrite existing package.json

Behavior:

Creates project directory if it does not exist. Generates a default raindrop.manifest with a “hello-world” application. Creates package.json, tsconfig.json, and required directory structure.

Fails if package.json exists without --overwrite flag. This prevents accidentally overwriting existing projects.

Example Output:

Terminal window
$ raindrop build init my-service
path: my-service
Initialized LiquidMetal.AI in my-service

Error Cases:

Terminal window
# Directory exists with package.json
$ raindrop build init existing-project
Error: A project existing-project has already been initialized.


# Use overwrite flag to proceed
$ raindrop build init existing-project --overwrite

Generate Command

Syntax: raindrop build generate

Generate TypeScript code from manifest definitions.

Flags:

  • -r, --root <path> - Project root directory (default: current directory)
  • -M, --manifest <file> - Manifest file name (default: raindrop.manifest)
  • -o, --output <dir> - Output directory for build artifacts (default: dist)

Behavior:

Parses the manifest file and validates syntax. Creates TypeScript type definitions in handler directories. Updates package.json with dependencies. Generates handler scaffolding code if handlers do not exist.

Run this command after changing the manifest to regenerate types. All handlers receive updated type definitions in their raindrop-types.ts files.

Example Output:

Terminal window
$ raindrop build generate
# Silently generates files, no output on success

Error Cases:

Terminal window
# Invalid manifest syntax
$ raindrop build generate
Error: Could not initialize project at .: Syntax error on line 12


# Missing manifest file
$ raindrop build generate -M missing.manifest
Error: Could not load manifest: ENOENT: no such file or directory

Deploy Command

Syntax: raindrop build deploy

Deploy application to Raindrop platform.

Flags:

  • -r, --root <path> - Project root directory (default: current directory)
  • -M, --manifest <file> - Manifest file name (default: raindrop.manifest)
  • -o, --output <dir> - Output directory (default: dist)
  • -v, --version <id> - Specific version ID to deploy
  • -s, --start - Start application immediately after deploy
  • --no-watch - Skip watching deployment status
  • -a, --amend - Amend existing version instead of creating new one
  • --lock <value> - Override lock ID to resume deployment

Behavior:

Validates project directory structure. Builds handler bundles. Uploads application code to Raindrop. Creates new version or amends existing version. Watches deployment status unless --no-watch specified.

Sandbox mode always runs in amend mode automatically. Full version deployments require full versioned deployments for updates.

Example Output:

Terminal window
$ raindrop build deploy --start
🔔 You deployed a full version, updates will require a full versioned deployment to work


📊 Watching deployment status...


hello-world@01jac6p20m4gahn1kaa2mhm2js
Status: RUNNING
Active: Yes


Modules:
  api-handler: RUNNING
    https://01jac6p20m4gahn1kaa2mhm2js.raindrop.liquidmetal.ai

Error Cases:

Terminal window
# Missing required files
$ raindrop build deploy
Error: Directory validation failed: Missing required file: package.json


Suggested actions:
  • Run 'raindrop build init' to initialize project
  • Ensure you're in correct directory


# Locked state prevents deployment
$ raindrop build deploy
Error: Operation not allowed: application is in a locked state

Status Command

Syntax: raindrop build status

Show deployment status and health of application.

Flags:

  • -r, --root <path> - Project root directory (default: current directory)
  • -M, --manifest <file> - Manifest file name (default: raindrop.manifest)
  • -a, --application <name> - Specific application name
  • -v, --version <id> - Specific version ID
  • -o, --output <format> - Output format: watch, table, json, compact (default: compact)

Behavior:

Queries Raindrop catalog for application status. Shows module states and URLs. Compact format shows summary information. Watch format refreshes status continuously. Table format shows detailed module information.

Fails with exit code 1 if application not found in catalog.

Example Output:

Terminal window
$ raindrop build status
hello-world@01jac6p20m4gahn1kaa2mhm2js
Status: RUNNING
Active: Yes


Modules:
  api-handler: RUNNING
    https://01jac6p20m4gahn1kaa2mhm2js.raindrop.liquidmetal.ai


$ raindrop build status -o table
┌─────────────┬─────────┬─────────────────────────────────────────────────┐
│ Module      │ Status  │ URLs                                            │
├─────────────┼─────────┼─────────────────────────────────────────────────┤
│ api-handler │ RUNNING │ https://01jac6p20m4gahn1kaa2mhm2js.raindrop... │
└─────────────┴─────────┴─────────────────────────────────────────────────┘

Error Cases:

Terminal window
# Application not found
$ raindrop build status -a nonexistent
Error: [not_found] Application not found

Start Command

Syntax: raindrop build start

Start a deployed application.

Flags:

  • -r, --root <path> - Project root directory (default: current directory)
  • -M, --manifest <file> - Manifest file name (default: raindrop.manifest)
  • -a, --application <name> - Application to start
  • -v, --version <id> - Version to start

Behavior:

Sets application version as active in catalog. Application must already be deployed. Fails if application is in locked state.

Example Output:

Terminal window
$ raindrop build start
Set hello-world@01jac6p20m4gahn1kaa2mhm2js as active.

Error Cases:

Terminal window
# Locked state prevents operation
$ raindrop build start
Error: Operation not allowed: application is in a locked state


# Version not specified
$ raindrop build start
Error: Expected a --version flag to be provided when a version is not currently set

Stop Command

Syntax: raindrop build stop

Stop a running application.

Flags:

  • -r, --root <path> - Project root directory (default: current directory)
  • -M, --manifest <file> - Manifest file name (default: raindrop.manifest)
  • -a, --application <name> - Application to stop
  • -v, --version <id> - Version to stop

Behavior:

Sets application version as inactive in catalog. Application remains deployed but stops serving traffic. Fails if application is in locked state.

Example Output:

Terminal window
$ raindrop build stop
Set hello-world@01jac6p20m4gahn1kaa2mhm2js as stopped.

Error Cases:

Terminal window
# Locked state prevents operation
$ raindrop build stop
Error: Operation not allowed: application is in a locked state

Branch Command

Syntax: raindrop build branch <branch>

Create new version branch from existing version.

Arguments:

  • <branch> - Branch name (required)

Flags:

  • -r, --root <path> - Project root directory (default: current directory)
  • -M, --manifest <file> - Manifest file name (default: raindrop.manifest)
  • -o, --output <dir> - Output directory (default: dist)
  • -p, --versionId <id> - Branch from this version (default: current version)
  • --start - Start application after branching
  • --no-watch - Skip watching deployment status
  • --show - Show current version without branching

Behavior:

Creates new version based on current or specified version. New branch is automatically marked as sandboxed. Deploys branch code and watches status. Fails if application is in locked or sandbox state.

Use branches to test changes without affecting production version. Sandboxed branches allow rapid iteration without version constraints.

Example Output:

Terminal window
$ raindrop build branch feature-auth
Branching complete, sandboxing the new branch
🔔 Branch is in Sandbox mode


📊 Watching deployment status...


hello-world@01jux6z20m4gbhn5kaa4mcm2jr
Status: RUNNING
Active: No


$ raindrop build branch --show
Current versionId: 01jac6p20m4gahn1kaa2mhm2js

Error Cases:

Terminal window
# Locked state prevents branching
$ raindrop build branch new-feature
Error: Operation not allowed: application is in a locked state


# Already in sandbox mode
$ raindrop build branch another-feature
Error: Branching is not allowed in sandbox mode

Checkout Command

Syntax: raindrop build checkout [version]

Switch current context to specific version.

Arguments:

  • [version] - Version ID to switch to (omit to show current version)

Flags:

  • -o, --output <format> - Output format: text, json (default: text)

Behavior:

Changes the active version in local configuration. Does not affect deployed applications. Subsequent commands operate on the checked-out version. Fails if application is in locked state.

Use checkout to switch between production and development versions. Local configuration persists across terminal sessions.

Example Output:

Terminal window
$ raindrop build checkout
Currently on version 01jac6p20m4gahn1kaa2mhm2js


$ raindrop build checkout 01jux6z20m4gbhn5kaa4mcm2jr
Switched to version 01jux6z20m4gbhn5kaa4mcm2jr


$ raindrop build checkout -o json
{
  "versionId": "01jux6z20m4gbhn5kaa4mcm2jr"
}

Error Cases:

Terminal window
# Locked state prevents checkout
$ raindrop build checkout 01jux6z20m4gbhn5kaa4mcm2jr
Error: Operation not allowed: application is in a locked state


# No version set
$ raindrop build checkout
No version set

Delete Command

Syntax: raindrop build delete [application]

Delete application versions from catalog.

Arguments:

  • [application] - Application name (default: from manifest)

Flags:

  • -r, --root <path> - Project root directory (default: current directory)
  • -M, --manifest <file> - Manifest file name (default: raindrop.manifest)
  • -o, --output <format> - Output format: text, table, json (default: table)
  • -v, --version <id> - Specific version to delete (default: current version)
  • -a, --all - Delete all versions of application

Behavior:

Removes application version from catalog. Deletes associated resources and configuration. The --all and --version flags are mutually exclusive. Defaults to current version if no flags specified.

Use delete to clean up unused development branches. Production versions should be deleted with caution.

Example Output:

Terminal window
$ raindrop build delete --version 01jux6z20m4gbhn5kaa4mcm2jr
Deleted hello-world at version 01jux6z20m4gbhn5kaa4mcm2jr


$ raindrop build delete --all
Deleted all versions of hello-world

Error Cases:

Terminal window
# Cannot use both flags
$ raindrop build delete --version 01jux6z20m4gbhn5kaa4mcm2jr --all
Error: --version and --all flags are mutually exclusive


# Application not found
$ raindrop build delete nonexistent
Error: Failed to delete application nonexistent: Application not found

Validate Command

Syntax: raindrop build validate

Run TypeScript type checking and build handlers.

Flags:

  • -r, --root <path> - Project root directory (default: current directory)
  • -M, --manifest <file> - Manifest file name (default: raindrop.manifest)
  • -o, --output <dir> - Output directory (default: dist)

Behavior:

Runs TypeScript compiler in check mode (tsc --noEmit). Builds handler bundles to verify code compiles. Does not deploy or modify deployed applications. Fails with exit code 1 if type errors detected.

Use validate before deploying to catch type errors early. This command runs faster than full deployment.

Example Output:

Terminal window
$ raindrop build validate
Using @liquidmetal-ai/raindrop-framework version 1.2.3
Running type check...
Type check passed

Error Cases:

Terminal window
# Type errors detected
$ raindrop build validate
Using @liquidmetal-ai/raindrop-framework version 1.2.3
Running type check...
src/handlers/api/index.ts(12,5): error TS2322: Type 'string' is not assignable to type 'number'.
Error: Type check failed. Please fix the TypeScript errors before building.

Environment Variables

Set Syntax: raindrop build env set <var> [value]

Get Syntax: raindrop build env get <var>

Manage environment variables and secrets for deployed applications.

Arguments:

  • <var> - Variable name in format env:KEY or handler:env:KEY
  • [value] - Variable value (use - to read from stdin)

Flags:

  • -r, --root <path> - Project root directory (default: current directory)
  • -M, --manifest <file> - Manifest file name (default: raindrop.manifest)
  • -v, --version <id> - Version ID (default: current version)
  • -a, --application <name> - Application name (default: from manifest)

Behavior:

Sets or retrieves environment variables for specific version. Variables defined as secrets in manifest are encrypted. Use stdin input (-) for multiline values or sensitive data. Changes take effect on next deployment amend.

Variable format uses colon-separated paths. Application-level variables use env:KEY. Handler-specific variables use handler-name:env:KEY.

Example Output:

Terminal window
$ raindrop build env set env:DATABASE_URL postgresql://localhost/mydb
set env:DATABASE_URL


$ raindrop build env get env:DATABASE_URL
env:DATABASE_URL=postgresql://localhost/mydb


# Set secret from stdin
$ echo "secret-api-key" | raindrop build env set env:API_KEY -
reading stdin (ctrl+D to finish)...
set env:API_KEY


# Get secret shows hash only
$ raindrop build env get env:API_KEY
env:API_KEY=[hash: a1b2c3d4...]

Error Cases:

Terminal window
# Variable not in manifest
$ raindrop build env set env:UNDEFINED_VAR value
Error: variable UNDEFINED_VAR not found in manifest


# Invalid variable format
$ raindrop build env set INVALID value
Error: variable must be an env variable or secret

Sandbox Commands

Sandbox Syntax: raindrop build sandbox

Unsandbox Syntax: raindrop build unsandbox

Mark versions as sandboxed or unsandboxed in catalog.

Flags:

  • --manifest <file> - Manifest file name
  • -v, --version <id> - Version ID to mark

Behavior:

Sandboxed versions allow rapid iteration without version constraints. All deployments to sandboxed versions run in amend mode automatically. Branches are automatically sandboxed on creation.

Use sandbox mode for development and testing. Unsandbox when ready to create production version.

Example Output:

Terminal window
$ raindrop build sandbox --version 01jux6z20m4gbhn5kaa4mcm2jr
Set hello-world@01jux6z20m4gbhn5kaa4mcm2jr as sandboxed.


$ raindrop build unsandbox --version 01jux6z20m4gbhn5kaa4mcm2jr
Set hello-world@01jux6z20m4gbhn5kaa4mcm2jr as unsandboxed.

Examples

Complete Deployment Workflow

Deploy a new application and start it immediately:

Terminal window
# Initialize project structure
raindrop build init my-app
cd my-app


# Edit raindrop.manifest to define your application
# Add handlers, databases, services


# Generate TypeScript types and handler scaffolding
raindrop build generate


# Write your handler logic in src/handlers/


# Deploy and start in one command
raindrop build deploy --start


# Monitor deployment progress
raindrop build status

This workflow accomplishes:

  • Creates project with default manifest
  • Generates type-safe code from manifest definitions
  • Validates manifest syntax during generation
  • Deploys application and watches deployment status
  • Starts application after successful deployment

Handle Deployment Failures

Fix missing environment variables after failed deployment:

Terminal window
# Deploy stops due to missing DATABASE_URL
raindrop build deploy
# Error: Missing required environment variable: DATABASE_URL


# Set the missing variable
raindrop build env set env:DATABASE_URL postgresql://localhost/mydb


# Resume deployment without creating new version
raindrop build deploy --amend --start

This workflow accomplishes:

  • Detects missing environment variables during deployment
  • Sets variables using proper namespace format (env:KEY)
  • Resumes deployment in amend mode to update existing version
  • Starts application after configuration fix

Version Management

Create and manage application branches:

Terminal window
# Create new branch from current version
raindrop build branch feature-auth


# Branch is automatically sandboxed
# Make changes to raindrop.manifest


# Deploy changes to branch
raindrop build deploy


# Switch back to main version
raindrop build checkout 01jac6p20m4gahn1kaa2mhm2js


# List all versions
raindrop build list


# Delete old branch
raindrop build delete --version 01jux6z20m4gbhn5kaa4mcm2jr

This workflow accomplishes:

  • Creates isolated branch for testing changes
  • Enables safe experimentation in sandbox mode
  • Allows switching between versions without data loss
  • Provides cleanup commands for unused versions
  • Lists all available versions for reference

Exit Codes

The raindrop build commands return the following exit codes:

  • 0 - Success - Command completed without errors
  • 1 - General error - Validation failures, file not found, locked state, missing requirements, type check failures
  • 5 - Not found - Application does not exist in catalog (status command only)