RestAPI Terminal (RAT)

RestAPI Terminal (RAT) is a command-line interface for managing your RestAPI.com APIs. Distributed as a single-file binary, it enables deployment of web applications, schema management, and API operations from local environments or CI/CD pipelines.

Installation

rat is a single self-contained launcher. Download it once and run it — it fetches and caches the right binary for your platform on first use.

Linux / macOS

curl -O https://docs.restapi.com/rat.cmd
sh rat.cmd login

Windows (PowerShell)

iwr https://docs.restapi.com/rat.cmd -OutFile rat.cmd
.\rat.cmd login

The launcher has no shebang, so always invoke it through a shell: sh rat.cmd <command> on Linux/macOS, .\rat.cmd <command> on Windows. A plain ./rat.cmd is not reliable.

Running it as rat

The examples in this guide use a bare rat for readability. To make that work, either drop the file on your PATH, or alias it:

# Option A: put it on PATH (Linux / macOS)
mkdir -p ~/.local/bin
mv rat.cmd ~/.local/bin/rat && chmod +x ~/.local/bin/rat
rat login   # requires ~/.local/bin on your PATH — add it in your shell profile if needed

# Option B: alias it in your shell
alias rat='sh /path/to/rat.cmd'

The rest of this page writes rat <command> — substitute sh rat.cmd <command> (or .\rat.cmd <command> on Windows) if you skipped the step above.

Versioning

You don't need to pin a version — rat always pulls the latest, and that's the recommended setup everywhere including CI. If you ever need a reproducible version, add a gg.toml to your project; otherwise there's nothing to manage.

Help

rat help

Authentication

Login

Authenticate with your RestAPI.com account:

rat login

This opens a browser for OAuth authentication. Your credentials are stored securely in the system keyring.

Logout

rat logout

Command Structure

Commands follow a hierarchical structure:

rat [global-options] <command> [subcommand] [options]

Global Options

Option	Description
-v, --verbose	Increase verbosity level
-w, --log-more	Enable detailed logging
-j, --json	Output as JSON (default is human-readable tables)
-y, --yes	Skip confirmation prompts (for scripts and automation)

Tenant Commands

List Tenants

rat tenant list

Tenant Files

Business tenants have shared files. Every Anton agent session on the tenant gets a read-only copy of them under /tenant, and a prompt.md at the top level is added to the agent's instructions. -t takes the tenant's name or ID; if you leave it out, RAT_TENANT is used.

rat tenant files -t acme list
rat tenant files -t acme upload ./branding                  # a folder: branding/include/a.css is stored as include/a.css
rat tenant files -t acme upload logo.png --prefix include   # stored as include/logo.png
rat tenant files -t acme download include/logo.png
rat tenant files -t acme download --all                     # every file, into ./tenant-files
rat tenant files -t acme download --all -o files.zip        # keep the zip as is
rat tenant files -t acme delete "include/**"

Things to know:

• Access: listing and downloading need access to the tenant. Uploading and deleting need a tenant owner.
• Hidden files: an upload skips dotfiles and dot folders. Pass --include-hidden to send them.
• Confirmation: at a terminal, an upload lists the files and asks first, a download asks before overwriting a local file, and a glob delete asks before deleting. In a script, an upload goes ahead and says how many existing files it replaced, but an overwriting download or a glob delete stops unless you pass --yes.
• Limits: the CLI won't take a tenant past 2000 files or 200 MB in total. Past that, the server refuses to bundle the files, so neither download --all nor Anton can fetch them.

API Commands

List APIs

rat api list --tenant <tenant-name>

Show API Details

rat api -a my-api show

Create API

rat api create --tenant my-tenant --name my-new-api --description "My API"

Delete API

rat api -a my-api delete

Schema Management

Get Schema

Download the current schema to schema.json:

rat api -a my-api schema get

Update Schema

Apply schema changes from a file:

rat api -a my-api schema update --prevent-breaking true

Use --prevent-breaking false to allow breaking changes (deletions, renames).

Validate Schema

Check schema without applying:

rat api -a my-api schema validate --prevent-breaking true

Deployment

Deploy Everything

Deploy webapp, schema, and functions in one command:

rat api -a my-api deploy

Default paths:

• Webapp: dist/
• Schema: schema.json
• Functions: functions/*.*

Custom paths:

rat api -a my-api deploy --dist build --schema api-schema.json --functions functions/*.*

Options:

Option	Description
--prevent-breaking	Prevent breaking schema changes (default: true)
--no-zip	Don't zip webapp files
--dry-run	Show what would be deployed

Pull from API

Download schema and functions from your API:

rat api -a my-api pull

Upload Webapp Files

rat api upload -a my-api ./dist --zip

Options:

Option	Description
-r, --relative-from	Control directory structure
-d, --delete-all	Delete existing files first
-z, --zip	Zip before upload (faster)

Virtual File System (VFS)

List Files

rat api -a my-api vfs list "**/*"

Upload Files

rat api -a my-api vfs upload "src/**/*.js" --base-path /scripts

Download Files

rat api -a my-api vfs download "logs/**/*.log" --output ./logs

Delete Files

rat api -a my-api vfs delete "tmp/**/*"

Functions

List Functions

rat api -a my-api function list

Show Function

rat api -a my-api function show --function <function-id>

Create a Function

rat api -a my-api function create http --file functions/orders.ts --endpoint /orders --access GET --access "POST=_AUTHENTICATED_USER"
rat api -a my-api function create timer --file functions/nightly.ts --timer-interval 1 --timer-frequency days --service-account runner

If the file doesn't exist yet, a starter template is created.

Run as a Service Account

--send-token sets which identity a function's calls to the API run as:

Value	Runs as
current-user	The user who triggered the function. This is the default for HTTP and data functions.
service-account	The account given with --service-account. Passing --service-account on its own implies this value.
none	No token, so the calls are anonymous. This is the default for timers.

A timer has no calling user, so without --service-account its calls to the API are anonymous. --service-account takes the account's name or client ID. It must be a data-management account, because only those have a user to run as. If two accounts share a name, use the client ID.

rat api -a my-api function update --function nightly --service-account runner
rat api -a my-api function update --function nightly --send-token none

An update keeps the function's current service account unless you pass a new one. To stop it running as that account, switch --send-token to another value.

Upload Function Code

rat api -a my-api function file --function <id> upload --file handler.js

Invoke Function

Test a function with input data:

rat api -a my-api function invoke --function <id> --file test-input.json

Local Code Execution

Run JavaScript/TypeScript locally with API context:

Run a File

rat run script.js

Run with API Context

rat run script.ts --api my-api

This provides access to:

• API tokens and secrets
• Built-in HTTP methods (get, post, put, patch, del)
• User context

Run with Function Config

Load configuration from an existing function:

rat run --api my-api --function my-function script.js

Run with Item Data

Fetch an item as input:

rat run --api my-api --collection products --item <item-id> handler.js

Run Inline Code

rat run --code "console.log('Hello from rat!')"

User Management

List Users

rat api -a my-api user list

Generate User Token

rat api -a my-api user token --user <user-id>

Options:

Option	Description
--skip-security-policy	Skip security policy validation
--skip-roles	Skip role validation
--skip-cascade	Skip cascade validation

Service Accounts

List Service Accounts

rat api -a my-api service-account list

Create Service Account

rat api -a my-api service-account create --name deployer --type api-management
rat api -a my-api service-account create --name runner    # data-management

--type picks what the account is for:

Type	Use it for
data-management (default)	Data changes and CI. Can do everything an api-management account can, and also gets a user in the API's user collection. It can sign in to the API itself as that user, so give the user roles for data access. Functions can run as this account.
api-management	Structural changes only (schema, functions, web app). It has no user in the API, so it can't sign in to the API itself or be a function's identity.

Whatever its type, a service account is an owner of the API. It can change the schema, functions and web app, and it can get admin tokens for the API's data, for example with rat api curl --admin. Guard its secret like an owner's password.

Manage Secrets

rat api -a my-api service-account secret --client-id <id> list
rat api -a my-api service-account secret --client-id <id> create

Roles

List Roles

rat api -a my-api role list

Manage Role Members

rat api -a my-api role member --role <id> list
rat api -a my-api role member --role <id> add --user <user-id>
rat api -a my-api role member --role <id> remove --user <user-id>

Secrets

List Secrets

rat api -a my-api secret list

Create Secret

rat api -a my-api secret create --key STRIPE_API_KEY --value sk_live_xxx

Delete Secret

rat api -a my-api secret delete --key STRIPE_API_KEY

Settings

List Settings

rat api -a my-api setting list

Jobs

List Jobs

rat api -a my-api job list

Start/Cancel Jobs

rat api -a my-api job start --job <id>
rat api -a my-api job cancel --job <id>

Data Export

Export as JSON

rat api -a my-api export json

Export as Blob

rat api -a my-api export blob

Data Access

The commands above manage your API as its owner. To work with an API's data (collections, views, queries) as an end user — with commands mapped live from its OpenAPI spec — use rat data:

rat data -a my-api login
rat data -a my-api users list --filter "age gt 18"

For owner/automation access to the same endpoints, rat api curl makes raw HTTP requests, and --admin skips roles and security policy:

rat api curl -a my-api /users --admin

See Data Access (rat data) for the full reference.

Billing

View Usage

rat api -a my-api billing usage
rat api -a my-api billing metrics

CI/CD Integration

For automated deployments, use service account credentials via environment variables:

Variable	Description
RAT_CLIENT_ID	Service account client ID
RAT_CLIENT_SECRET	Service account secret

GitHub Actions Example

name: Deploy API

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install rat
        run: |
          mkdir -p "$HOME/.local/bin"
          curl -o "$HOME/.local/bin/rat" https://docs.restapi.com/rat.cmd
          chmod +x "$HOME/.local/bin/rat"
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Deploy
        env:
          RAT_CLIENT_ID: ${{ secrets.RAT_CLIENT_ID }}
          RAT_CLIENT_SECRET: ${{ secrets.RAT_CLIENT_SECRET }}
        run: |
          rat api -a my-api deploy --dry-run
          rat api -a my-api deploy

Simple Upload

For basic webapp deployment in CI/CD:

sh rat.cmd upload -a <api-name-or-id> <directory>

Output Formats

By default, rat outputs human-readable tables. Use --json for machine-readable output:

# Table format (default)
rat api list --tenant my-tenant

# JSON format
rat api list --tenant my-tenant --json

Tips

• Use -a shorthand for --api in most commands
• The --dry-run flag shows what would happen without making changes
• Combine with jq for JSON processing: rat api list -j | jq '.[] | .name'
• Store API name in environment: export RAT_API=my-api

---

The rat launcher is powered by gg.cmd — a single cross-platform file that downloads and caches the right binary for your OS. rat.cmd is just gg.cmd shipped as the rat applet, so there's nothing else to install.