npm package: @rainfaces/cli
Description: AI-native CLI for Rainface
Latest version: 0.1.0

# Rainface CLI (`rainface`)

AI-native command line interface for Rainface with two usage modes:

- Chat mode (`rainface chat`) for natural-language workflows with tool calling.
- Deterministic command mode for explicit operations (`me`, `models`, `submit`, etc.).

## Quickstart

From repo root:

```bash
npm run cli:build
node sdk/cli/dist/bin.js help
```

To run locally as a command:

```bash
cd sdk/cli
npm run build
chmod +x dist/bin.js
./dist/bin.js help
```

## Configuration

Precedence is:

1. CLI flags
2. Environment variables
3. Config file (`~/.config/rainface/config.json`)

Run interactive setup:

```bash
node sdk/cli/dist/bin.js init
```

Environment variables:

- `RAINFACE_API_KEY`
- `RAINFACE_MCP_BASE_URL`
- `RAINFACE_AI_API_KEY`
- `RAINFACE_AI_PROVIDER` (`openai` or `gemini`)
- `RAINFACE_AI_BASE_URL`
- `RAINFACE_AI_MODEL`

Gemini quick setup:

```bash
node sdk/cli/dist/bin.js init --ai-provider gemini
```

Or with env vars:

```bash
export RAINFACE_AI_PROVIDER=gemini
export RAINFACE_AI_API_KEY="<your_gemini_key>"
```

## Commands

```bash
rainface init
rainface chat
rainface chat "show my stats"
rainface chat --prompt "show my stats"
echo "show my stats" | rainface chat
rainface tools list
rainface tools call rainface_public_stats
echo '{"history":true,"limit":5}' | rainface tools call rainface_price --args -
rainface me
rainface models
rainface predictions --limit 20 --offset 0
rainface round
rainface stats
rainface price
rainface price --history --limit 30
rainface submit --model-id <uuid> --proof-file proof.json
cat proof.json | rainface submit --model-id <uuid> --proof-file -
rainface submit --model-id <uuid> --proof-file proof.json --confirm
rainface doctor
rainface help submit
```

## Chat Modes

- Interactive REPL: `rainface chat`
- One-shot positional prompt: `rainface chat "show my stats"`
- One-shot prompt: `rainface chat --prompt "show my stats"`
- One-shot piped stdin: `echo "show my stats" | rainface chat`

`rainface chat ...` (positional or `--prompt`) cannot be combined with piped stdin in the same invocation.

## JSON Events (`rainface chat --json`)

Chat JSON output is newline-delimited event objects:

```json
{"type":"chat.start","mode":"oneshot_prompt","tool_count":8}
{"type":"chat.tool_result","tool":"rainface_public_stats","status":"ok","result":{"ok":true,"tool":"rainface_public_stats","status":200,"data":{"total_models":10},"error":null,"meta":{"request_id":"req_1","timestamp":"2026-02-21T00:00:00.000Z","upstream":"public-api/stats"}}}
{"type":"chat.assistant","content":"Here are your current stats ..."}
{"type":"chat.end","mode":"oneshot_prompt","reason":"completed","assistant_messages":1,"tool_calls":1}
```

Deterministic commands (`me`, `models`, `submit`, etc.) keep their existing `--json` response shape.

## Validation

- Unknown flags are rejected with usage errors.
- Value flags require explicit values (for example, `--limit <n>`).

## Submit Safety

- Submit commands are dry-run by default.
- Real writes require explicit `--confirm` in command mode.
- Chat mode asks for confirmation before real writes when stdin is interactive.
- If a real write is confirmed and `idempotency_key` is missing, the CLI generates one.