Skip to main content

Data Access (rat data)

rat data calls a hosted API's data endpoints — its collections, views, and queries — from the command line. Unlike rat api, which manages your API as its owner, rat data acts as an end user of the API and signs in against that API's own hosted login.

Commands are not hardcoded: rat data reads the API's OpenAPI spec from /_openapi at runtime and builds the available commands and flags live. When you add a collection or property, it shows up in rat data automatically — no upgrade required.

rat data vs rat api curl

Both reach the same data endpoints, but with different identities:

  • rat data authenticates as an end user of the API (per-API login, scoped by that user's roles). Use it to work with data the way a real user would.
  • rat api curl --admin authenticates with your platform account (rat login) and acts as admin, skipping roles and security policy. Use it for automation and scripting where you own the API.

If you are already signed in with rat login, prefer rat api curl — see Raw HTTP requests below.

Authentication​

Login​

Sign in as an end user of the API. This opens a browser for the API's hosted login (OAuth 2.0 authorization code with PKCE):

rat data -a my-api login

Tokens are stored securely in the system keyring (per API) and refreshed automatically. The browser callback uses a local loopback address, so no redirect URI configuration is required.

Logout​

rat data -a my-api logout

Useful for piping into other tools:

rat data -a my-api token

Service accounts (headless)​

For CI or automation, authenticate with a service account instead of a browser login. Set these environment variables and rat data uses the client-credentials grant automatically:

VariableDescription
RAT_DATA_CLIENT_IDService account client ID (an API user of type serviceaccount)
RAT_DATA_CLIENT_SECRETService account secret

Listing available commands​

Run rat data with no action to list the commands mapped from the API's spec:

rat data -a my-api

Show the details — verbs, path parameters, query flags, and request-body fields — for a single collection:

rat data -a my-api users

Working with collections​

Each collection exposes a set of verbs derived from the spec:

VerbHTTPDescription
listGET /collectionList records (aliases: ls)
get <id>GET /collection/{id}Get one record (alias: show)
addPOST /collectionCreate a record (aliases: create, new)
update <id>PATCH /collection/{id}Partially update a record
replace <id>PUT /collection/{id}Replace a record
delete <id>DELETE /collection/{id}Delete a record (aliases: rm, del, remove)
# List, filter, and page (query parameters come straight from the spec)
rat data -a my-api users list --filter "age gt 18" --sort-by name- --page-size 5

# Get one record by id
rat data -a my-api users get 42

# Create a record
rat data -a my-api users add name=Bob age:=42

# Update some fields
rat data -a my-api users update 42 --name Alice

# Delete
rat data -a my-api users delete 42

You can also call an operation by its operationId directly:

rat data -a my-api getUsersById 42

Value syntax​

Fields and parameters use a compact shorthand on the command line:

SyntaxMeaningExample
key=valueRequest body field (string, or coerced to the schema's type)name=Bob
key:=jsonRequest body field, parsed as raw JSONage:=42, tags:='["a","b"]'
key==valueQuery-string parametercount==true
--key valueNamed flag for a spec parameter or body field--page-size 5

For larger bodies, pipe JSON on standard input — explicit fields override what's piped:

echo '{"name":"Bob","age":42}' | rat data -a my-api users add
cat user.json | rat data -a my-api users add name=Override

Raw requests​

When you want to hit a path directly rather than go through the mapped commands, pass a method and path. A leading / defaults to GET:

# GET
rat data -a my-api /users

# Other methods
rat data -a my-api post /users name=Bob
rat data -a my-api delete /users/42

The same value syntax (key=value, key:=json, key==value) applies.

Targeting an API​

-a accepts either a short API name or a full base URL:

rat data -a my-api /users                       # https://my-api.restapi.cloud/api
rat data -a https://my-api.restapi.cloud /users # explicit base URL

You can also set RAT_API to avoid repeating -a:

export RAT_API=my-api
rat data users list

Raw HTTP requests (rat api curl)​

If you own the API and are signed in with rat login, rat api curl makes admin requests to the same data endpoints without a separate per-API login. With --admin it skips roles and security policy:

rat api curl -a my-api /users --admin
rat api curl -a my-api /users -X POST -d '{"name":"Bob"}' --admin
rat api curl -a my-api /users -u alice --admin    # act as a specific user
tip

Use rat data to exercise your API as an end user (respecting roles), and rat api curl --admin for owner/automation access. See the RestAPI Terminal reference for the full rat api command set.

Using rat data with Claude​

rat data is a natural fit for letting an AI assistant such as Claude work with your API's data on your behalf — for example in Claude cowork, where Claude acts as an end user the way a teammate would.

You don't need a pre-built integration. Claude learns tasks from skills: short Markdown files with a name, a description, and plain instructions. The description tells Claude when to use the skill; the body tells it how. Creating one for your API takes a couple of minutes.

A skill that wraps rat data looks like this:

---
name: my-api-data
description: Read and update records in My API. Use when the user asks to list, create, or change My API data (e.g. tasks).
---

Use the `rat data` command-line tool to work with My API's data.
The user signs in once with `rat data -a my-api login`.

List records (filter and page with flags from the API's spec):

```bash
rat data -a my-api tasks list --filter "done==false" --page-size 20
```

Create a record:

```bash
rat data -a my-api tasks add title="Write the docs" done:=false
```

Update a record by id:

```bash
rat data -a my-api tasks update 42 --done true
```

Save it where your Claude environment loads skills from (commonly a skills/ folder — see Claude's skill documentation for your setup), and Claude will offer it whenever the request matches the description. Because the available commands are mapped live from the API's spec, the skill keeps working as your collections evolve.

Unattended use

For runs without a person present (scheduled jobs, automations), give the skill a service account instead of an interactive login by setting RAT_DATA_CLIENT_ID and RAT_DATA_CLIENT_SECRET.

See also​

Last updated on