Examples Verified (100%)

Commands

The trc command-line interface is the primary tool for working with T-Ruby. It compiles .trb files to Ruby, type-checks your code, and generates RBS signatures.

Overview

trc [command] [options] [files...]

Available commands:

compile - Compile T-Ruby files to Ruby and RBS
watch - Watch files and auto-compile on changes
check - Type-check without generating output
init - Initialize a new T-Ruby project

compile

Compiles T-Ruby source files (.trb) to Ruby (.rb) and RBS (.rbs) files.

Basic Usage

# Compile a single file
trc compile hello.trb

# Compile multiple files
trc compile user.trb post.trb

# Compile all .trb files in directory
trc compile src/

# Compile current directory
trc compile .

Shorthand

The compile command is the default, so you can omit it:

trc hello.trb
trc src/
trc .

Options

# Specify output directory
trc compile src/ --output build/

# Generate only Ruby files (skip RBS)
trc compile src/ --no-rbs

# Generate only RBS files (skip Ruby)
trc compile src/ --rbs-only

# Specify RBS output directory
trc compile src/ --rbs-dir sig/

# Use specific config file
trc compile src/ --config trc.production.yaml

# Clean output directory before compilation
trc compile . --clean

# Show verbose output
trc compile . --verbose

# Suppress all output except errors
trc compile . --quiet

Examples

Compile with custom output directories:

trc compile src/ \
  --output build/ \
  --rbs-dir signatures/

Compile for production (clean build, no debug info):

trc compile . \
  --clean \
  --quiet \
  --no-debug-info

Compile and preserve source structure:

trc compile src/ \
  --output build/ \
  --preserve-structure

This transforms:

src/
├── models/
│   └── user.trb
└── services/
    └── auth.trb

Into:

build/
├── models/
│   └── user.rb
└── services/
    └── auth.rb

Exit Codes

0 - Success
1 - Compilation errors
2 - Type errors
3 - Configuration errors

watch

Watches T-Ruby files and automatically recompiles when changes are detected. Perfect for development workflows.

Basic Usage

# Watch current directory
trc watch

# Watch specific directory
trc watch src/

# Watch multiple directories
trc watch src/ lib/

Options

# Clear terminal on each rebuild
trc watch --clear

# Run command after successful compilation
trc watch --exec "bundle exec rspec"

# Debounce delay in milliseconds (default: 100)
trc watch --debounce 300

# Watch additional file patterns
trc watch --include "**/*.yaml"

# Ignore specific patterns
trc watch --ignore "**/test/**"

# Exit after first successful compilation
trc watch --once

Examples

Watch and run tests on success:

trc watch src/ --exec "bundle exec rake test"

Watch with custom debounce:

# Wait 500ms after last change before compiling
trc watch --debounce 500

Watch configuration files too:

trc watch src/ --include "trbconfig.yml"

Output

Watch mode provides real-time feedback:

Watching for file changes in src/...

[10:30:15] Changed: src/models/user.trb
[10:30:15] Compiling...
[10:30:16] ✓ Compiled successfully (1.2s)
[10:30:16] Generated:
  - build/models/user.rb
  - sig/models/user.rbs

Waiting for changes...

If there are errors:

[10:31:20] Changed: src/models/user.trb
[10:31:20] Compiling...
[10:31:21] ✗ Compilation failed

Error: src/models/user.trb:15:23
  Type mismatch: expected String, got Integer

    @email = user_id
              ^^^^^^^

Waiting for changes...

Keyboard Shortcuts

While watch mode is running:

Ctrl+C - Stop watching and exit
r - Force recompilation
c - Clear terminal
q - Quit

check

Type-check T-Ruby files without generating output. Useful for CI/CD pipelines and quick validation.

Basic Usage

# Check a single file
trc check hello.trb

# Check multiple files
trc check src/**/*.trb

# Check entire directory
trc check .

Options

# Strict mode (fail on warnings)
trc check . --strict

# Show warnings as well as errors
trc check . --warnings

# Report format (text, json, junit)
trc check . --format json

# Output report to file
trc check . --output-file report.json

# Max number of errors to show (default: 50)
trc check . --max-errors 10

# Continue on first error (default: stop after 50 errors)
trc check . --no-error-limit

Examples

Check before committing:

# Add to .git/hooks/pre-commit
#!/bin/sh
trc check . --strict

Generate JSON report for tooling:

trc check . \
  --format json \
  --output-file type-errors.json

Quick check with minimal output:

trc check src/ --quiet --max-errors 5

Output Formats

Text (default):

Checking 15 files...

Error: src/models/user.trb:23:15
  Type mismatch: expected String, got Integer

    return user_id
           ^^^^^^^

Error: src/services/auth.trb:45:8
  Undefined method 'authenticate' on nil

    user.authenticate(password)
    ^^^^

✗ Found 2 errors in 2 files

JSON:

{
  "files_checked": 15,
  "errors": [
    {
      "file": "src/models/user.trb",
      "line": 23,
      "column": 15,
      "severity": "error",
      "message": "Type mismatch: expected String, got Integer",
      "code": "type-mismatch"
    }
  ],
  "summary": {
    "error_count": 2,
    "warning_count": 0,
    "files_with_errors": 2
  }
}

JUnit XML (for CI integration):

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite name="T-Ruby Type Check" tests="15" failures="2">
    <testcase name="src/models/user.trb">
      <failure message="Type mismatch: expected String, got Integer">
        Line 23, column 15
      </failure>
    </testcase>
  </testsuite>
</testsuites>

Exit Codes

0 - No errors found
1 - Type errors found
2 - Warnings found (only with --strict)

init

Initialize a new T-Ruby project with configuration file and directory structure.

Basic Usage

# Create trbconfig.yml in current directory
trc --init

# Interactive setup
trc --init --interactive

# Use a template
trc --init --template rails

Options

# Skip prompts and use defaults
trc --init --yes

# Specify project name
trc --init --name my-project

# Choose template (basic, rails, gem, sinatra)
trc --init --template rails

# Create directory structure
trc --init --create-dirs

# Initialize git repository
trc --init --git

Templates

Basic (default):

trc --init --template basic

Creates:

trbconfig.yml
src/
build/
sig/

Rails:

trc --init --template rails

Creates configuration for Rails projects:

source:
  include:
    - app/models
    - app/controllers
    - app/services
    - lib

output:
  ruby_dir: app
  preserve_structure: true

compiler:
  strictness: standard

types:
  external:
    - rails
    - activerecord

Gem:

trc --init --template gem

Creates configuration for gem development:

source:
  include:
    - lib
  exclude:
    - "**/*_spec.trb"

output:
  ruby_dir: lib
  rbs_dir: sig
  preserve_structure: true

compiler:
  strictness: strict
  generate_rbs: true

Sinatra:

trc --init --template sinatra

Creates configuration for Sinatra apps:

source:
  include:
    - app
    - lib

output:
  ruby_dir: build
  rbs_dir: sig

compiler:
  strictness: standard

types:
  external:
    - sinatra

Interactive Mode

trc --init --interactive

Guides you through setup:

T-Ruby Project Setup
====================

? Project name: my-awesome-project
? Project type: (Use arrow keys)
  ❯ Basic
    Rails
    Gem
    Sinatra
    Custom

? Source directory: src
? Output directory: build
? RBS directory: sig

? Strictness level: (Use arrow keys)
    Strict (all code must be typed)
  ❯ Standard (public APIs must be typed)
    Permissive (minimal requirements)

? Generate RBS files? Yes
? Target Ruby version: 3.2

? Create directory structure? Yes
? Initialize git repository? Yes

✓ Created trbconfig.yml
✓ Created src/
✓ Created build/
✓ Created sig/
✓ Initialized git repository

Your T-Ruby project is ready! Try:

  trc compile src/
  trc watch src/

Examples

Quick start a new project:

mkdir my-project
cd my-project
trc --init --yes --create-dirs

Rails project setup:

cd my-rails-app
trc --init --template rails --interactive

Gem development:

bundle gem my_gem
cd my_gem
trc --init --template gem --create-dirs

Global Options

These options work with all commands:

# Show version
trc --version
trc -v

# Show help
trc --help
trc -h

# Show help for specific command
trc compile --help

# Use specific config file
trc --config path/to/trbconfig.yml

# Set log level (debug, info, warn, error)
trc --log-level debug

# Enable color output (default: auto)
trc --color

# Disable color output
trc --no-color

# Show stack traces on errors
trc --stack-trace

Configuration File

Commands respect the trbconfig.yml configuration file. Command-line options override config file settings.

Example workflow:

trbconfig.yml
source:
  include:
    - src
  exclude:
    - "**/*_test.trb"

output:
  ruby_dir: build
  rbs_dir: sig

compiler:
  strictness: standard
  generate_rbs: true

Then simply run:

# Uses settings from trbconfig.yml
trc compile
trc watch
trc check

CI/CD Usage

GitHub Actions

- name: Type Check
  run: trc check . --format junit --output-file test-results.xml

- name: Compile
  run: trc compile . --quiet

GitLab CI

typecheck:
  script:
    - trc check . --strict
    - trc compile .

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit

# Get staged .trb files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.trb$')

if [ -n "$STAGED_FILES" ]; then
  echo "Type checking staged files..."
  trc check $STAGED_FILES --strict

  if [ $? -ne 0 ]; then
    echo "Type check failed. Commit aborted."
    exit 1
  fi
fi

Tips and Best Practices

Development Workflow

Use watch mode during development:

trc watch src/ --clear --exec "bundle exec rspec"

Run check before committing:
```
trc check . --strict
```
Use quiet mode in scripts:
```
trc compile . --quiet || exit 1
```

Performance

Compile specific files instead of entire directories when possible:
```
# Faster
trc compile src/models/user.trb

# Slower
trc compile src/
```
Use --no-rbs if you don't need RBS files:
```
trc compile . --no-rbs
```
Increase debounce in watch mode for large projects:
```
trc watch --debounce 500
```

Troubleshooting

Command not found:

# Check installation
which trc

# Reinstall if needed
gem install t-ruby

Slow compilation:

# Use verbose mode to see what's taking time
trc compile . --verbose

# Check configuration
trc compile . --log-level debug

Unexpected output location:

# Check your configuration
cat trbconfig.yml

# Or specify explicitly
trc compile src/ --output build/ --rbs-dir sig/

Next Steps

Configuration Reference - Learn about trbconfig.yml options
Compiler Options - Detailed compiler flags and settings
Project Configuration - Set up your project

Overview​

compile​

Basic Usage​

Shorthand​

Options​

Examples​

Exit Codes​

watch​

Basic Usage​

Options​

Examples​

Output​

Keyboard Shortcuts​

check​

Basic Usage​

Options​

Examples​

Output Formats​

Exit Codes​

init​

Basic Usage​

Options​

Templates​

Interactive Mode​

Examples​

Global Options​

Configuration File​

CI/CD Usage​

GitHub Actions​

GitLab CI​

Pre-commit Hook​

Tips and Best Practices​

Development Workflow​

Performance​

Troubleshooting​

Next Steps​

Overview

compile

Basic Usage

Shorthand

Options

Examples

Exit Codes

watch

Basic Usage

Options

Examples

Output

Keyboard Shortcuts

check

Basic Usage

Options

Examples

Output Formats

Exit Codes

init

Basic Usage

Options

Templates

Interactive Mode

Examples

Global Options

Configuration File

CI/CD Usage

GitHub Actions

GitLab CI

Pre-commit Hook

Tips and Best Practices

Development Workflow

Performance

Troubleshooting

Next Steps