Embr CLI

CLI and interactive TUI for the Embr platform. Manage projects, deployments, environments, and more — directly from the terminal.

Quick Start

# Requires Node.js 20+
npm install -g @embr-platform/cli

# Login
embr login

# Launch interactive TUI
embr

# Or use commands directly
embr projects list

Interactive TUI

Run embr with no arguments to launch the interactive terminal UI. Built with React Ink, it provides an RPG-style menu system for navigating the platform without memorizing commands.

From the TUI you can:

• Browse and manage projects
• Trigger and monitor deployments
• Configure environment variables
• View activity logs and environment stats

PR Preview Environments

Open a pull request against any project's repo and Embr automatically deploys a preview environment for it (named pr-<branch>-<number>). The embr-platform GitHub App posts the preview URL on the PR, redeploys on each new commit, and tears the env down when the PR is closed. See environments docs for variable inheritance, naming, and lifecycle details.

All features available via CLI commands are also accessible through the TUI.

Commands

Authentication

embr login                  # Authenticate with Embr
embr logout                 # Clear credentials
embr auth status            # Check current auth state

Projects

embr projects list
embr projects get <id>
embr projects create --repo <owner/repo> --installation-id <id>
embr projects update <id> --name "New Name"
embr projects delete <id>
embr projects from-template --template <name>

Environments

embr environments list <projectId>
embr environments get <projectId> <envId>
embr environments create <projectId> --name staging --branch main
embr environments update <projectId> <envId> --branch develop
embr environments delete <projectId> <envId>
embr environments scale <projectId> <envId> --replicas 3
embr environments scale-status <projectId> <envId>
embr environments stats <projectId> <envId>
embr environments processes <projectId> <envId>

Deployments

embr deployments list -p <projectId> -e <envId>
embr deployments get <deploymentId> -p <projectId> -e <envId>
embr deployments create -p <projectId> -e <envId> --commit <sha>
embr deployments cancel <deploymentId> -p <projectId> -e <envId>
embr deployments activate <deploymentId> -p <projectId> -e <envId>
embr deployments rollback <deploymentId> -p <projectId> -e <envId>
embr deployments instances <deploymentId> -p <projectId> -e <envId>
embr deployments snapshots <deploymentId> -p <projectId> -e <envId>

Variables

embr variables list -p <projectId> -e <envId>
embr variables set <key> <value> -p <projectId> -e <envId>     # secrets: append --secret
embr variables delete <key> -p <projectId> -e <envId>

Repos

embr repos list                     # List connected repositories
embr repos branches <owner/repo>    # List branches for a repo

Activity

embr activity list -p <projectId>   # View recent activity for a project

Databases

embr dbs templates                  # List available DB templates
embr dbs create-template --template postgres --base-image <image>
embr dbs snapshot --template postgres --sandbox-id <id> --engine postgres
embr dbs restore --snapshot <snapshotId> --sandbox-id <id>
embr dbs snapshots --sandbox-id <id>

Shell

embr shell                          # Open an interactive shell session

Logs

embr logs -p <projectId> -e <envId> # Stream environment logs

Config

embr config get                     # Show current configuration
embr config set apiUrl <url>        # Set a config value
embr config reset                   # Reset to defaults

Development

Prerequisites

Install the Azure Artifacts credential provider (one-time):

npm install --global @microsoft/artifacts-npm-credprovider --registry https://pkgs.dev.azure.com/artifacts-public/PublicTools/_packaging/AzureArtifacts/npm/registry/

Then authenticate in the src/Embr.Cli directory:

cd src/Embr.Cli
artifacts-npm-credprovider

Commands

npm install
npm run dev              # Run in dev mode (ts-node, no build needed)
npm run build            # Compile TypeScript
npm run lint             # ESLint
npm run format           # Prettier
npm test                 # Vitest
npm run test:watch       # Vitest watch mode
npm run test:coverage    # Coverage report

Local linking

You can use npm link during development to test the CLI globally:

npm run link:dev         # Build + npm link

Reverting a local link: npm link overwrites the published install. To restore:

npm unlink -g @embr-platform/cli
npm install -g @embr-platform/cli

Building & Distribution

The CLI ships as an npm package to npmjs.com.

npm run build            # TypeScript → dist/ → embr-bundle.mjs

The release pipeline (release-cli.yml) handles version stamping, publishing, and GitHub Release creation automatically.

Architecture

src/
├── cli.ts               # CLI entry point (Commander.js)
├── shared/              # Shared types, API client, config, auth
├── commands/            # CLI command handlers
├── tui/                 # Interactive TUI (React Ink)
│   ├── App.tsx          # TUI root + router
│   ├── screens/         # TUI screens
│   └── components/      # Reusable TUI components
└── utils/               # CLI output helpers