@aspects-ai/workspace-cli

Lightweight CLI for installing libraries into workspaces. Designed to be AI-friendly and CI/CD compatible.

Features

• Simple, non-interactive commands
• Git-based library installation via sparse checkout
• Environment variable authentication only (no prompts)
• Automatic dependency management
• Tracks installed libraries in workspace.config.json

Installation

npm install -g @aspects-ai/workspace-cli

Or use with npx:

npx @aspects-ai/workspace-cli <command>

Prerequisites

• Node.js >= 18.0.0
• Git installed and available in PATH
• GitHub personal access token (for private repositories)

Authentication

Set the WORKSPACE_CLI_TOKEN environment variable with your GitHub personal access token:

export WORKSPACE_CLI_TOKEN=ghp_xxxxxxxxxxxx

The token needs read access to the repositories containing the libraries.

Commands

init

Initialize workspace configuration. Creates workspace.config.json in the current workspace.

workspace-cli init

list

List all available libraries in the registry.

workspace-cli list

Example output:

Available libraries:

  animate-core @0.1.3
    Core animation components for Noodle videos

Total: 1 library

add <library>

Install a library into the workspace.

WORKSPACE_CLI_TOKEN=ghp_xxx workspace-cli add animate-core

Options:

• -f, --force - Force reinstall if already installed

The command will:

1. Fetch the library from the git repository
2. Install it to ./core/<library-name>/
3. Update workspace.config.json
4. Add dependencies to package.json

update <library>

Update an installed library to the latest version from the repository.

WORKSPACE_CLI_TOKEN=ghp_xxx workspace-cli update animate-core

This command will:

1. Check the currently installed version
2. Fetch the latest version from the git repository
3. Overwrite the existing files
4. Update workspace.config.json with the new version and commit hash
5. Update dependencies in package.json if they changed

create-remotion-entry

Generate a remotion-entry.tsx file for server-side rendering of Remotion compositions.

workspace-cli create-remotion-entry

Options:

• -o, --output <path> - Output path for remotion-entry.tsx (default: remotion-entry.tsx)
• -f, --compositions-dir <path> - Path to compositions directory (default: compositions)

This command will:

1. Scan the compositions directory for all composition subdirectories
2. Validate that each composition has a main.tsx file
3. Generate a remotion-entry.tsx file with all compositions imported and registered
4. Display the list of registered compositions

Example output:

[INFO] Scanning compositions in: compositions
[SUCCESS] Created remotion entry file: /path/to/remotion-entry.tsx

Registered 3 compositions(s):
  • example
  • healthee
  • peregrine

Next steps:
  Render a composition: ANIMATION_SSR_MODE=true npx remotion render remotion-entry.tsx <composition-id> output.mp4

The generated file can be used with Remotion CLI for server-side rendering:

# Render a specific composition
ANIMATION_SSR_MODE=true npx remotion render remotion-entry.tsx example output.mp4

# List available compositions
ANIMATION_SSR_MODE=true npx remotion compositions remotion-entry.tsx

Usage Examples

Basic Workflow

# Navigate to your workspace
cd my-workspace

# Initialize workspace config
workspace-cli init

# View available libraries
workspace-cli list

# Install a library (requires token)
export WORKSPACE_CLI_TOKEN=ghp_xxxxxxxxxxxx
workspace-cli add animate-core

# Install dependencies
npm install

CI/CD Usage

# .github/workflows/setup.yml
name: Setup Workspace

on: [push]

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install libraries
        env:
          WORKSPACE_CLI_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          npx @aspects-ai/workspace-cli add animate-core

      - name: Install dependencies
        run: npm install

AI Agent Usage

The CLI is designed to be used by AI agents without any interactive prompts:

# All commands fail fast with clear error messages
# No confirmation prompts
# Machine-readable output

WORKSPACE_CLI_TOKEN=$TOKEN workspace-cli add animate-core

Configuration

workspace.config.json

The CLI creates and manages workspace.config.json in your workspace:

{
  "version": "1.0",
  "coreDir": "./core",
  "libraries": {
    "animate-core": {
      "version": "0.1.3",
      "installedAt": "2025-10-15T12:34:56Z",
      "commit": "097cf62abc123"
    }
  }
}

Library Registry

Libraries are defined in src/registry/libraries.json:

{
  "libraries": {
    "animate-core": {
      "name": "@aspects-ai/noodle-animate-core",
      "description": "Core animation components for Noodle videos",
      "repository": {
        "url": "https://github.com/aspects-ai/noodle-templates.git",
        "directory": "noodle-animate-core/src",
        "branch": "main",
        "packageJsonPath": "noodle-animate-core/package.json"
      },
      "installPath": "animate-core"
    }
  }
}

Automatic Detection: The CLI automatically reads both the version and dependencies from the library's package.json in the git repository. You don't need to hardcode these values in the registry - they're always fetched from the source of truth.

How It Works

1. Git Sparse Checkout: The CLI uses git sparse checkout to efficiently fetch only the required directory from the repository
2. Automatic Metadata Detection: Both version and dependencies are read from the library's package.json in the repository, so they're always up-to-date
3. Local Installation: Files are copied to ./core/<library-name>/ in your workspace
4. Dependency Management: Required dependencies are automatically added to your package.json
5. Version Tracking: The exact git commit hash and detected version are stored for reproducibility

Error Handling

All errors are reported to stderr with clear, actionable messages:

# Missing token
Error: WORKSPACE_CLI_TOKEN environment variable is required

# Not in workspace
Error: Not a workspace directory. Could not find package.json.

# Library not found
Error: Library 'invalid-name' not found in registry.
Available libraries: animate-core

# Already installed
Error: Library 'animate-core' is already installed at version 0.1.3.
Use --force to reinstall.

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

# Development mode (watch)
npm run dev

Adding New Libraries

To add a new library to the registry:

1. Add the library definition to src/registry/libraries.json
2. Ensure the library source is available in a git repository
3. Test installation with workspace-cli add <library-name>

Example:

{
  "my-library": {
    "name": "@aspects-ai/my-library",
    "description": "Description of the library",
    "repository": {
      "url": "https://github.com/org/repo.git",
      "directory": "path/to/library/src",
      "branch": "main",
      "packageJsonPath": "path/to/library/package.json"
    },
    "installPath": "my-library"
  }
}

Note: Both version and dependencies fields are optional. If you provide packageJsonPath, the CLI will automatically read these from the library's package.json in the repository. This keeps the registry minimal and ensures values are always current.

License

ISC