status | Ralph TUI

Synopsis

Bash

ralph-tui status [options]

The status command displays the current session state without starting execution. It's designed for scripts, CI pipelines, and quick status checks.

INFO

Use --json for machine-readable output in automation scripts and CI/CD pipelines.

Options

Option	Description
`--json`	Output in JSON format for CI/scripts
`--cwd <path>`	Working directory (where to find the session file)

Examples

Basic Status Check

Bash

# Check status in current directory
ralph-tui status

Example output:

Session Status: active
Current Iteration: 7
Tasks: 3/10 completed
Active Task: US-005 - Implement user authentication
Last Updated: 2024-01-15 14:32:00

JSON Output for Scripts

Bash

# Get JSON output for parsing
ralph-tui status --json

Example JSON output:

JSON

{
  "status": "active",
  "iteration": 7,
  "tasks": {
    "total": 10,
    "completed": 3,
    "inProgress": 1,
    "pending": 6
  },
  "activeTask": {
    "id": "US-005",
    "title": "Implement user authentication"
  },
  "lastUpdated": "2024-01-15T14:32:00.000Z",
  "locked": true
}

Check Status in Different Directory

Bash

# Check status of a session in another project
ralph-tui status --cwd /path/to/project

Status Values

The status field can be one of:

Status	Description
`active`	Session is currently running or paused
`completed`	All tasks are finished
`no_session`	No session file found
`stale`	Session appears abandoned (old lock)

Use in CI/CD Pipelines

The --json flag makes it easy to integrate with CI systems:

Bash

#!/bin/bash
# Check if Ralph is done
status=$(ralph-tui status --json | jq -r '.status')
 
if [ "$status" = "completed" ]; then
  echo "All tasks completed!"
  exit 0
elif [ "$status" = "active" ]; then
  echo "Still running..."
  exit 1
fi

GitHub Actions Example

YAML

- name: Check Ralph Status
  run: |
    status=$(ralph-tui status --json | jq -r '.status')
    completed=$(ralph-tui status --json | jq -r '.tasks.completed')
    total=$(ralph-tui status --json | jq -r '.tasks.total')
    echo "Ralph: $completed/$total tasks completed (status: $status)"

Polling for Completion

You can use status to poll for completion in scripts:

Bash

#!/bin/bash
# Poll until completed or timeout
timeout=3600  # 1 hour
interval=60   # Check every minute
elapsed=0
 
while [ $elapsed -lt $timeout ]; do
  status=$(ralph-tui status --json | jq -r '.status')
 
  if [ "$status" = "completed" ]; then
    echo "Done!"
    exit 0
  fi
 
  sleep $interval
  elapsed=$((elapsed + interval))
done
 
echo "Timeout waiting for completion"
exit 1

Session File Location

The status command looks for .ralph-tui/session.json in:

The directory specified by --cwd
The current working directory (if --cwd not specified)

run - Start a new execution session
resume - Continue an interrupted session
logs - View detailed iteration output