Tirsa Factory CLI

0.2.19 verified Sat May 09 auth: no javascript

Tirsa Factory CLI (v0.2.19) is a thin HTTP client that dispatches AI-powered software factory pipelines from the terminal. Commands delegate to a remote Command Center for project creation, pipeline scheduling, and human-gate approvals. Pipeline execution runs on Trigger.dev cloud or a local worker for filesystem access. Requires Node.js 20+. Designed for the Tirsa Factory ecosystem (TwinPilot-based), not a general-purpose CLI.

Common errors

error Error: Cannot find module 'tirsa-factory-cli' ↓

cause Package not installed or not found in PATH when using global install.

fix

Install globally with 'npm install -g tirsa-factory-cli' or use npx: 'npx tirsa-factory-cli login'

error Error: Node.js version must be >=20. Current version is 18.x.x ↓

cause Using an older Node.js version.

fix

Upgrade Node.js to v20 or later (e.g., via nvm: 'nvm install 20')

error Error: Authentication failed. No valid profile or API key found. ↓

cause Not logged in and no env vars set.

fix

Run 'tirsa-factory login' interactively, or set TIRSA_API_KEY, TIRSA_TENANT, TIRSA_FACTORY environment variables.

error Error: Cannot find Command Center at <url>. Check network or TIRSA_COMMAND_CENTER_URL ↓

cause Network unreachable or wrong URL (default https://tirsa-factory.vercel.app).

fix

Ensure network access and correct URL. Optionally override via TIRSA_COMMAND_CENTER_URL env var.

Warnings

breaking Requires Node.js >=20. Older versions will not run. ↓

fix Upgrade Node.js to version 20 or higher.

gotcha CLI is a thin client; most logic runs server-side. Offline or network issues will break all commands except 'doctor'. ↓

fix Ensure network connectivity to Command Center URL (default: https://tirsa-factory.vercel.app).

gotcha API keys are factory-scoped. Leaked keys can only operate within that factory, but still sensitive. ↓

fix Store keys securely, rotate regularly, use env vars in CI, never commit to source control.

deprecated No breaking changes deprecated yet in v0.2.x. Watch for future semver bumps. ↓

fix Pin version in CI to avoid unexpected breaking changes.

gotcha The 'login' command opens a browser; headless CI environments require env var authentication. ↓

fix Use TIRSA_API_KEY, TIRSA_TENANT, TIRSA_FACTORY env vars instead of interactive login.

Install

npm install tirsa-factory-cli

yarn add tirsa-factory-cli

pnpm add tirsa-factory-cli

Imports

cli
wrong
```
import cli from 'tirsa-factory-cli'
```
correct
```
npx tirsa-factory <command>
```
This is a CLI tool, not a library. Run via npx or global install.
environment variables
wrong
```
require('tirsa-factory-cli').setApiKey(...)
```
correct
```
export TIRSA_API_KEY=sk_live_...; tirsa-factory login
```
Authentication is done via login command or env vars, not programmatic API.

commands

wrong

tirsaFactory.fromScratch('project idea')

correct

tirsa-factory from-scratch "project idea"

All interactions are CLI commands, not function calls.

Quickstart

Shows installation, browser-based login, creating a project from scratch, checking status, and approving a gate, plus CI env var usage.

#!/usr/bin/env bash
# Install globally
npm install -g tirsa-factory-cli

# Login (opens browser)
tirsa-factory login

# Create a new project from scratch
tirsa-factory from-scratch "Meal planning app for busy parents"

# Check status of projects
tirsa-factory status

# View pending human gates
tirsa-factory pending

# Approve a gate (replace <run-id> with actual ID)
tirsa-factory approve <run-id> --comment "looks good"

# Or use env vars for CI
TIRSA_API_KEY=sk_live_example TIRSA_TENANT=acme TIRSA_FACTORY=main tirsa-factory status