### REI3 Command-Line Interface (CLI) Examples

Source: https://context7.com/r3-team/r3/llms.txt

Manage REI3 installations and operations using the `r3` binary. Common tasks include installing as a service, running interactively, creating admin users, and setting data directories.

```bash
# Install as a system service
sudo ./r3 -install
```

```bash
# Run interactively from the console (uses config.json in same directory)
./r3 -run
```

```bash
# Run with HTTP (dev/testing only)
./r3 -run -http
```

```bash
# Run with a custom config file
./r3 -run -config /etc/rei3/config.json
```

```bash
# Create an admin user (useful after fresh install)
./r3 -newadmin admin:MySecretPassword
```

```bash
# Use external www directory instead of embedded one (development)
./r3 -run -wwwpath ./www
```

```bash
# Set data directory paths and write them to config
./r3 -setdata /opt/rei3/data
```

```bash
# Start/stop/uninstall service
sudo ./r3 -start
sudo ./r3 -stop
sudo ./r3 -uninstall
```

```bash
# Build the binary with a specific version
go build -ldflags "-X main.appVersion=3.2.0.4246"
```

--------------------------------

### Import Module (`POST /import`)

Source: https://context7.com/r3-team/r3/llms.txt

Import a .rei3 package file to install or upgrade an application module. This is submitted as a multipart upload and requires admin privileges.

```bash
# Import/install a module package (admin token required)
curl -k -X POST "https://localhost/import" \
  -F "token=$TOKEN" \
  -F "transfer=@/path/to/my_module.rei3"
```

--------------------------------

### Export Module (`GET /export/`)

Source: https://context7.com/r3-team/r3/llms.txt

Export a REI3 application module as a .rei3 package file. This is useful for backups, sharing, or installation on other instances. Requires admin privileges.

```bash
# Export module (admin token required)
curl -k -o "my_module.rei3" \
  "https://localhost/export/?token=$TOKEN&module_id=550e8400-e29b-41d4-a716-446655440050"
```

--------------------------------

### Build REI3 Executable with Version

Source: https://github.com/r3-team/r3/blob/main/README.md

Compile the REI3 source code using Go, specifying a custom application version. Ensure Golang is installed and navigate to the source code directory before running.

```bash
go build -ldflags "-X main.appVersion={YOUR_APP_VERSION}"
```

--------------------------------

### Module Import

Source: https://context7.com/r3-team/r3/llms.txt

Import a `.rei3` package file to install or upgrade an application module on the instance. Requires admin privileges. The file is submitted as a multipart upload.

```APIDOC
## Module Import (`POST /import`)

Import a `.rei3` package file to install or upgrade an application module on the instance. Requires admin privileges. The file is submitted as a multipart upload.

### Parameters

#### Request Body (multipart/form-data)
- **token** (string) - Required - Admin authentication token.
- **transfer** (file) - Required - The `.rei3` package file to import.

### Request Example
```bash
curl -k -X POST "https://localhost/import" \
  -F "token=$TOKEN" \
  -F "transfer=@/path/to/my_module.rei3"
```
```

--------------------------------

### Export Data to CSV (`GET /csv/download/`)

Source: https://context7.com/r3-team/r3/llms.txt

Export application data as a CSV file. All query parameters, including relations, joins, expressions, filters, and orders, are passed as JSON-encoded URL query parameters.

```bash
# Export records to CSV (token in URL, not Authorization header)
curl -k -o "export.csv" "https://localhost/csv/download/?token=$TOKEN\
&relation_id=550e8400-e29b-41d4-a716-446655440001\
&joins=%5B%5D\
&expressions=%5B%7B%22attributeId%22%3A%22550e8400-e29b-41d4-a716-446655440002%22%2C%22index%22%3A0%7D%5D\
&filters=%5B%5D\
&orders=%5B%5D\
&columns=%5B%7B%22attributeId%22%3A%22550e8400-e29b-41d4-a716-446655440002%22%2C%22captions%22%3A%7B%7D%7D%5D\
&date_format=Y-m-d\
&timezone=Europe%2FBerlin\
&bool_false=No\
&bool_true=Yes\
&char_comma=%2C\
&char_dec=.
&char_thou=\
&ignore_header=false\
&total_limit=10000"
```

--------------------------------

### Download File (`GET /data/download/`)

Source: https://context7.com/r3-team/r3/llms.txt

Use this endpoint to download files from REI3. You can specify a version or download the latest. Thumbnails for images and PDFs are also available.

```bash
# Download latest version of a file
curl -k -O "https://localhost/data/download/document.pdf?token=$TOKEN\
&attribute_id=550e8400-e29b-41d4-a716-446655440001\
&file_id=550e8400-e29b-41d4-a716-446655440123"
```

```bash
# Download a specific version
curl -k -O "https://localhost/data/download/document.pdf?token=$TOKEN\
&attribute_id=550e8400-e29b-41d4-a716-446655440001\
&file_id=550e8400-e29b-41d4-a716-446655440123\
&version=2"
```

```bash
# Download thumbnail (for images/PDFs)
curl -k -O "https://localhost/data/download/thumb/?token=$TOKEN\
&attribute_id=550e8400-e29b-41d4-a716-446655440001\
&file_id=550e8400-e29b-41d4-a716-446655440123"
```

--------------------------------

### Construct and Execute Data GET Query

Source: https://context7.com/r3-team/r3/llms.txt

Use `data.Get_tx` to translate a structured `DataGet` request into a PostgreSQL query. It handles relations, joins, expressions, filters, and ordering. The generated SQL query is available for logging, even on error.

```go
import (
    "r3/data"
    "r3/types"
    "github.com/jackc/pgx/v5/pgtype"
)

dataGet := types.DataGet{
    RelationId:  relationUUID,     // UUID of the base relation
    IndexSource: 0,                // index of source relation (0 = base)
    Limit:       50,
    Offset:      0,
    Joins: []types.DataGetJoin{{
        AttributeId: joinAttributeUUID,
        Index:       1,
        IndexFrom:   0,
        Connector:   "LEFT",
    }},
    Expressions: []types.DataGetExpression{{
        AttributeId: pgtype.UUID{Bytes: attrUUID, Valid: true},
        Index:       0,
    }},
    Filters: []types.DataGetFilter{{
        Connector: "AND",
        Index:     0,
        Operator:  "=",
        Side0: types.DataGetFilterSide{
            AttributeId: pgtype.UUID{Bytes: statusAttrUUID, Valid: true},
        },
        Side1: types.DataGetFilterSide{Value: "active"},
    }},
    Orders: []types.DataGetOrder{{
        AttributeId: pgtype.UUID{Bytes: nameAttrUUID, Valid: true},
        Ascending:   true,
    }},
}

var sqlQuery string
results, totalCount, err := data.Get_tx(ctx, tx, dataGet, loginId, &sqlQuery)
if err != nil {
    // sqlQuery is filled for error logging even on failure
    log.Printf("query failed: %v\nSQL: %s", err, sqlQuery)
}
// results[i].Values     — attribute values in expression order
// results[i].IndexRecordIds — map[int]any: record IDs per relation index
// totalCount            — total matching rows (without LIMIT)
```

--------------------------------

### Module Export

Source: https://context7.com/r3-team/r3/llms.txt

Export a REI3 application module as a `.rei3` package file for backup, sharing, or installation on another instance. Requires admin privileges.

```APIDOC
## Module Export (`GET /export/`)

Export a REI3 application module as a `.rei3` package file for backup, sharing, or installation on another instance. Requires admin privileges.

### Parameters

#### Query Parameters
- **token** (string) - Required - Admin authentication token.
- **module_id** (string) - Required - The ID of the module to export.

### Request Example
```bash
curl -k -o "my_module.rei3" \
  "https://localhost/export/?token=$TOKEN&module_id=550e8400-e29b-41d4-a716-446655440050"
```
```

--------------------------------

### REST API - GET Records (`GET /api/{module}/{api_name}/{version}`)

Source: https://context7.com/r3-team/r3/llms.txt

Retrieve records from a published REST API endpoint. Supports pagination, filtering via URL parameters, verbose output, and single-record lookup by ID. Ensure you include the Bearer token in the Authorization header.

```bash
# List records (default output: array of value arrays)
curl -s -k "https://localhost/api/lsw_invoices/contracts/v1?limit=10&offset=0" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

```bash
# Verbose mode: returns named objects per relation index
curl -s -k "https://localhost/api/lsw_invoices/contracts/v1?verbose=1&limit=5" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

```bash
# Response (verbose=1):
# [
#   {
#     "0(contracts)": { "title": "Contract A", "amount": 5000 },
#     "1(customer)":  { "name": "Acme Corp" }
#   }
# ]
```

```bash
# Filter records using defined filter attribute as URL param
curl -s -k "https://localhost/api/lsw_invoices/contracts/v1?status=active&limit=20" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

--------------------------------

### Single Record Lookup

Source: https://context7.com/r3-team/r3/llms.txt

Retrieve a single record by its ID using a GET request.

```APIDOC
## GET /api/lsw_invoices/contracts/v1/{record_id}

### Description
Retrieves a single record by its unique identifier.

### Method
GET

### Endpoint
/api/lsw_invoices/contracts/v1/{record_id}

### Parameters
#### Path Parameters
- **record_id** (string) - Required - The unique identifier of the record to retrieve.

### Request Example
```bash
curl -s -k "https://localhost/api/lsw_invoices/contracts/v1/45" \
  -H "Authorization: Bearer $TOKEN" | jq .
```
```

--------------------------------

### REI3 Configuration File (`config.json`)

Source: https://context7.com/r3-team/r3/llms.txt

This JSON file configures REI3 settings, including database connection details, file paths, and web server options. Ensure database credentials are set before first launch.

```json
{
  "cluster": {
    "nodeId": ""
  },
  "db": {
    "embedded": false,
    "host": "localhost",
    "port": 5432,
    "name": "rei3",
    "user": "rei3",
    "pass": "strongpassword",
    "ssl": true,
    "sslSkipVerify": false,
    "connsMax": 20,
    "connsMin": 2
  },
  "mirror": false,
  "paths": {
    "certificates": "data/certificates/",
    "embeddedDbBin": "pgsql16/bin/",
    "embeddedDbData": "data/database/",
    "files": "data/files/",
    "fileExport": "",
    "fileImport": "",
    "temp": "data/temp/",
    "transfer": "data/transfer"
  },
  "portable": false,
  "web": {
    "cert": "cert.crt",
    "key": "cert.key",
    "listen": "0.0.0.0",
    "port": 443,
    "tlsMinVersion": "1.2"
  }
}
```

--------------------------------

### Connect and Authenticate via WebSocket (Username/Password)

Source: https://context7.com/r3-team/r3/llms.txt

Establish a WebSocket connection and authenticate using username and password. This is the first step in WebSocket communication, followed by data requests.

```javascript
// Connect to REI3 WebSocket
const ws = new WebSocket('wss://localhost/websocket');

// Step 1: Authenticate (must be the sole request in the transaction)
ws.onopen = () => {
  ws.send(JSON.stringify({
    transactionNr: 1,
    requests: [{
      ressource: "auth",
      action:    "user",
      payload:   JSON.stringify({ username: "admin", password: "admin" })
    }]
  }));
};

// Step 2: Handle auth response, then send data requests
ws.onmessage = (event) => {
  const res = JSON.parse(event.data);
  // transactionNr: 0  => unrequested server push (schemaLoaded, configChanged, etc.)
  // transactionNr: N  => response matching request N
  console.log(res);
};

// Server-pushed (unrequested) event types:
// "schemaLoaded"         - module schema was reloaded (includes moduleIdMapData)
// "schemaLoading"        - schema reload in progress
// "configChanged"        - system configuration changed
// "collectionChanged"    - a data collection was updated
// "filesCopied"          - files were copied
// "fileRequested"        - a file action was requested
// "jsFunctionCalled"     - a JS function was triggered server-side
// "keystrokesRequested"  - keyboard input requested for a client
// "reauthorized"         - session token was renewed

```

--------------------------------

### Import Data from CSV (`POST /csv/upload`)

Source: https://context7.com/r3-team/r3/llms.txt

Import records into an application relation from a CSV file. This is submitted as multipart form data, including the token, target relation, column mappings, and the CSV file itself.

```bash
# Upload a CSV for import (multipart)
curl -k -X POST "https://localhost/csv/upload" \
  -F "token=$TOKEN" \
  -F "relation_id=550e8400-e29b-41d4-a716-446655440001" \
  -F "attribute_ids=["550e8400-e29b-41d4-a716-446655440002","550e8400-e29b-41d4-a716-446655440003"]" \
  -F "file=@/path/to/import.csv"
```

--------------------------------

### ICS Calendar Feed (`GET /ics/download/`)

Source: https://context7.com/r3-team/r3/llms.txt

Expose a REI3 calendar field as an iCalendar (.ics) feed. This is useful for integrating with external calendar applications. Authentication uses a fixed token tied to a specific login.

```bash
# Subscribe to a calendar feed in any ICS-compatible client
# URL format: /ics/download/?field_id=UUID&login_id=N&token_fixed=TOKEN
curl -k "https://localhost/ics/download/?field_id=550e8400-e29b-41d4-a716-446655440099\
&login_id=3\
&token_fixed=my-fixed-ics-token" \
  -o calendar.ics
```

```text
# The feed returns standard iCalendar data:
# BEGIN:VCALENDAR
# VERSION:2.0
# PRODID:-//REI3//iCAL access
# METHOD:PUBLISH
# BEGIN:VEVENT
# DTSTART:20240115
# DTEND:20240116
# SUMMARY:Project Kickoff
# URL:https://rei3.example.com/#/app/mymod/form/uuid/42
# END:VEVENT
# END:VCALENDAR
```

--------------------------------

### Create PostgreSQL Database for REI3

Source: https://github.com/r3-team/r3/blob/main/www/help/en_us_admin.html

Create a new PostgreSQL database for REI3, assigning ownership to a specific user, setting the template to template0, and ensuring UTF8 encoding.

```sql
CREATE DATABASE my_rei3_db WITH OWNER = my_rei3_user TEMPLATE = template0 ENCODING = 'UTF8';
```

--------------------------------

### Backup PostgreSQL Database with pg_dump

Source: https://github.com/r3-team/r3/blob/main/www/help/en_us_admin.html

Use pg_dump to create a full backup of the REI3 PostgreSQL database. Specify the host, port, user, format, and target directory for the backup.

```bash
pg_dump -h HOSTNAME -p 5432 -U USERNAME -Fd -f TARGETDIR
```

--------------------------------

### REST API - GET Records

Source: https://context7.com/r3-team/r3/llms.txt

Retrieve records from an application's published REST API endpoint. Supports pagination (`limit`, `offset`), filtering via URL query parameters, verbose mode, and single-record lookup by appending the record ID.

```APIDOC
## REST API — GET Records (`GET /api/{module}/{api_name}/{version}`)

### Description
Retrieve records from an application's published REST API endpoint. Supports pagination (`limit`, `offset`), filtering via URL query parameters, verbose mode, and single-record lookup by appending the record ID.

### Method
GET

### Endpoint
`/api/{module}/{api_name}/{version}`

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of records to return.
- **offset** (integer) - Optional - The number of records to skip.
- **verbose** (integer) - Optional - If set to 1, returns named objects per relation index.
- **filter_attribute** (string) - Optional - Used to filter records based on a specific attribute's value.

### Request Example
```bash
# List records (default output: array of value arrays)
curl -s -k "https://localhost/api/lsw_invoices/contracts/v1?limit=10&offset=0" \
  -H "Authorization: Bearer $TOKEN" | jq . 

# Verbose mode: returns named objects per relation index
curl -s -k "https://localhost/api/lsw_invoices/contracts/v1?verbose=1&limit=5" \
  -H "Authorization: Bearer $TOKEN" | jq . 

# Filter records using defined filter attribute as URL param
curl -s -k "https://localhost/api/lsw_invoices/contracts/v1?status=active&limit=20" \
  -H "Authorization: Bearer $TOKEN" | jq . 
```

### Response
#### Success Response (200)
- The response format depends on the `verbose` parameter. Without `verbose`, it's an array of value arrays. With `verbose=1`, it's an array of objects where keys represent relation indices and values are the record objects.

#### Response Example (verbose=1)
```json
[
  {
    "0(contracts)": { "title": "Contract A", "amount": 5000 },
    "1(customer)":  { "name": "Acme Corp" }
  }
]
```
```

--------------------------------

### Authenticate User and Generate JWT

Source: https://context7.com/r3-team/r3/llms.txt

Use `login_auth.User` to authenticate a user with credentials and optional MFA tokens. If successful, it returns a JWT token. Use `login_auth.Token` to validate an existing JWT token.

```go
// Authenticate a user (internal use):
result, err := login_auth.User(ctx, "john.doe", "password123",
    pgtype.Int4{},   // mfaTokenId  (invalid = not providing 2nd factor)
    pgtype.Text{})   // mfaTokenPin (invalid = not providing 2nd factor)

if err != nil {
    // err.Error() == "AUTH_ERROR" for failed auth
    // result.MfaTokens != nil if MFA is required but PIN not given yet
}

// result.Token    — signed JWT string to return to client
// result.Id       — login ID
// result.Admin    — is admin
// result.NoAuth   — public/no-auth login
// result.SaltKdf  — KDF salt for E2EE key derivation

// Authenticate via existing token (used in REST API handler):
login, err := login_auth.Token(ctx, bearerTokenString)
// login.Id, login.Admin, login.LanguageCode, etc.

// Token payload structure (JWT claims):
// {
//   "iss": "r3 application",
//   "sub": "john.doe",
//   "exp": 1234567890,
//   "iat": 1234500000,
//   "admin": false,
//   "loginId": 42,
//   "type": "local",   // "local" | "ldap" | "oauth" | "fixed" | "noAuth"
//   "noAuth": false
// }
```

--------------------------------

### Recover PostgreSQL Database with pg_restore

Source: https://github.com/r3-team/r3/blob/main/www/help/en_us_admin.html

Use pg_restore to recover a full backup of the REI3 PostgreSQL database from a directory. Ensure to specify the host, port, user, target database, and source directory.

```bash
pg_restore -h HOSTNAME -p 5432 --no-owner -U USERNAME -d TARGETDBNAME SOURCEDIR
```

--------------------------------

### Create/Update Records (REST API - Non-verbose)

Source: https://context7.com/r3-team/r3/llms.txt

Create new records or update existing ones using a non-verbose POST request. Values are provided in column order. The response contains the new record ID.

```bash
# Non-verbose POST: values in column order
curl -s -k -X POST "https://localhost/api/lsw_invoices/contracts/v1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[null, "New Contract", 9500, "active"]' | jq .
# Response: {"0": 123}  (relation index -> new record ID)
```

--------------------------------

### REST API Authentication (`POST /api/auth`)

Source: https://context7.com/r3-team/r3/llms.txt

Obtain a JWT Bearer token by sending credentials to the `/api/auth` endpoint. This token is required for all subsequent REST API requests and should be passed in the `Authorization` header.

```bash
# Obtain a JWT bearer token
curl -s -X POST https://localhost/api/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}' \
  | jq .
```

```bash
# Response:
# {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
```

```bash
# Store token for reuse
TOKEN=$(curl -s -X POST https://localhost/api/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}' \
  | jq -r .token)
```

--------------------------------

### Cross-Compile REI3 for Different OS

Source: https://github.com/r3-team/r3/blob/main/README.md

Cross-compile the REI3 binary for different operating systems by setting the GOOS environment variable. This allows building executables for platforms other than the current one.

```bash
GOOS=windows go build -ldflags "-X main.appVersion=2.5.1.2980"
```

```bash
GOOS=linux go build -ldflags "-X main.appVersion=2.5.1.2980"
```

--------------------------------

### Upload New File (REST API)

Source: https://context7.com/r3-team/r3/llms.txt

Upload a new file using a multipart form data POST request. Provide the token, attribute ID, an empty file ID, and the file itself. The response contains the ID of the newly created file.

```bash
# Upload a new file (fileId empty = new file)
curl -s -k -X POST "https://localhost/data/upload" \
  -F "token=$TOKEN" \
  -F "attributeId=550e8400-e29b-41d4-a716-446655440001" \
  -F "fileId=" \
  -F "file=@/path/to/document.pdf" | jq .
# Response: {"id": "550e8400-e29b-41d4-a716-446655440123"}
```