CLI Tools

The Ultimo CLI provides commands for generating TypeScript clients, managing projects, and development workflows.

Installation

Install the CLI from your Ultimo project:

cargo install --path ultimo-cli

Or use the installation script:

./install-cli.sh

Verify installation:

ultimo --version
# ultimo 0.1.0

Commands

Generate Client

Generate a TypeScript client from your Rust backend:

ultimo generate --project ./backend --output ./frontend/src/lib/client.ts

Short form:

ultimo generate -p ./backend -o ./frontend/src/client.ts

This command:

Analyzes your Rust RPC definitions
Extracts type information
Generates a type-safe TypeScript client
Writes it to the specified output file

Example Output

// Auto-generated by Ultimo CLI
// DO NOT EDIT MANUALLY
 
export interface User {
  id: number;
  name: string;
  email: string;
}
 
export interface GetUserInput {
  id: number;
}
 
export class UltimoRpcClient {
  private baseUrl: string;
 
  constructor(baseUrl: string = "/rpc") {
    this.baseUrl = baseUrl;
  }
 
  async getUser(params: GetUserInput): Promise<User> {
    return this.call("getUser", params);
  }
 
  // ... more methods
}

Workflow Integration

Development Script

Add client generation to your development workflow:

#!/bin/bash
# dev.sh
 
echo "🔄 Generating TypeScript client..."
ultimo generate -p ./backend -o ./frontend/src/lib/client.ts
 
echo "🚀 Starting backend..."
cd backend && cargo run --release &
BACKEND_PID=$!
 
echo "🎨 Starting frontend..."
cd frontend && npm run dev &
FRONTEND_PID=$!
 
# Cleanup on exit
trap "kill $BACKEND_PID $FRONTEND_PID" EXIT
 
wait

Watch Mode

Regenerate client on backend changes:

#!/bin/bash
# watch-generate.sh
 
echo "👁️  Watching for changes..."
 
while true; do
  inotifywait -r -e modify ./backend/src
  echo "🔄 Regenerating client..."
  ultimo generate -p ./backend -o ./frontend/src/lib/client.ts
done

Pre-commit Hook

Ensure client is up-to-date before commits:

# .git/hooks/pre-commit
#!/bin/bash
 
echo "🔄 Regenerating TypeScript client..."
ultimo generate -p ./backend -o ./frontend/src/lib/client.ts
 
if [ $? -eq 0 ]; then
  git add frontend/src/lib/client.ts
  echo "✅ Client updated and staged"
else
  echo "❌ Client generation failed"
  exit 1
fi

CI/CD Pipeline

# .github/workflows/ci.yml
name: CI
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Install Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
 
      - name: Install Ultimo CLI
        run: cargo install --path ultimo-cli
 
      - name: Generate TypeScript client
        run: ultimo generate -p ./backend -o ./frontend/src/lib/client.ts
 
      - name: Check for changes
        run: |
          if ! git diff --quiet; then
            echo "❌ TypeScript client is out of date"
            exit 1
          fi
 
      - name: Run tests
        run: cargo test

Configuration File

Create ultimo.toml for project-specific settings:

[project]
name = "my-app"
version = "1.0.0"
 
[generate]
backend_path = "./backend"
output_path = "./frontend/src/lib/client.ts"
base_url = "/api/rpc"
 
[dev]
backend_port = 3000
frontend_port = 5173
hot_reload = true

Then use:

ultimo generate  # Uses config file settings

Future Commands

These commands are coming soon:

New Project

# Create new Ultimo project
ultimo new my-app --template fullstack
 
# Templates available:
# - api: REST API server
# - rpc: RPC-only server
# - fullstack: Backend + frontend
# - minimal: Bare bones setup

Development Server

# Start with hot reload
ultimo dev --port 3000
 
# Watch and restart on changes
ultimo dev --watch
 
# With frontend proxy
ultimo dev --proxy http://localhost:5173

Build

# Production build
ultimo build --profile release
 
# With optimizations
ultimo build --profile release --strip --lto
 
# Cross-compilation
ultimo build --target x86_64-unknown-linux-musl

Test

# Run all tests
ultimo test
 
# Run specific test
ultimo test integration
 
# With coverage
ultimo test --coverage

Format & Lint

# Format code
ultimo fmt
 
# Check formatting
ultimo fmt --check
 
# Run linter
ultimo lint
 
# Fix linting issues
ultimo lint --fix

CLI Help

View help for any command:

# General help
ultimo --help
 
# Command-specific help
ultimo generate --help
ultimo dev --help
ultimo build --help

Best Practices

✅ Automate Generation

Add to your build script:

{
  "scripts": {
    "prebuild": "ultimo generate",
    "build": "vite build",
    "dev": "ultimo generate && vite"
  }
}

✅ Version Control

Commit the generated client to track changes:

# .gitignore

# Don't ignore generated client
!frontend/src/lib/client.ts

✅ Verify in CI

Ensure the client is always up-to-date:

- name: Verify client is up-to-date
  run: |
    ultimo generate
    git diff --exit-code frontend/src/lib/client.ts

✅ Document Commands

Add to your README:

## Development
 
Generate TypeScript client:
\`\`\`bash
ultimo generate -p ./backend -o ./frontend/src/lib/client.ts
\`\`\`
 
Start development servers:
\`\`\`bash
./dev.sh
\`\`\`

Troubleshooting

Client Generation Fails

# Ensure backend compiles
cd backend && cargo check
 
# Verify project structure
ultimo generate --verbose
 
# Check output path is writable
touch ./frontend/src/lib/client.ts

Outdated Client

# Regenerate client
ultimo generate -p ./backend -o ./frontend/src/lib/client.ts
 
# Clear frontend build cache
cd frontend && rm -rf node_modules/.vite

CLI Not Found

# Reinstall CLI
cargo install --path ultimo-cli --force
 
# Add to PATH
export PATH="$HOME/.cargo/bin:$PATH"
 
# Verify
which ultimo
ultimo --version