Berth
Request a berth

Docs

Use Berth from the command line

A berth is one app. You get a Postgres database and a token. The CLI and the HTTP API do the same work. You do not need this website after you have a token.

Install

This downloads one Python 3 script. No pip install.

curl -fsSL https://atberth.com/install.sh | sh

That writes ~/.local/bin/berth. If that folder is not on your PATH, the installer tells you the line to add. Then run berth --help.

Login

Save a token on this machine. You are prompted, so the token is not in your shell history. The file is ~/.config/berth/config.json, mode 600.

berth login

Scripts can pass it without a prompt:

berth login --token "$TOKEN"
berth login < token.txt

Check what was saved:

berth whoami

Create an app

This needs the admin token. The name is the slug: 2 to 32 characters, a letter first, then lowercase letters, numbers, or underscore.

berth apps create demo

Berth creates a database for that app and prints an app token once. The CLI stores it next to your login. Same call with curl, using the admin token:

curl -sS -X POST https://api.atberth.com/v1/apps \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo"}'

A new app answers 201 with id, slug, and token. The token is not shown again.

Create a table

Use the app token, or the admin token. Types are text, integer, boolean, and timestamptz. Berth always adds id (uuid) and created_at.

berth tables create --app demo notes body:text
curl -sS -X POST https://api.atberth.com/v1/apps/demo/tables \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"notes","columns":[{"name":"body","type":"text"}]}'

Add a row

Send the column values. id and created_at are filled in for you.

berth rows add --app demo notes body=hello

The same insert with curl. $TOKEN here is the app token printed by berth apps create (the admin token also works):

curl -sS -X POST https://api.atberth.com/v1/apps/demo/tables/notes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"hello"}'

Read it back. Copy id from the insert response.

berth rows get --app demo notes "$ID"
curl -sS https://api.atberth.com/v1/apps/demo/tables/notes/$ID \
  -H "Authorization: Bearer $TOKEN"

berth login

Saves a token. --token skips the prompt. If stdin is not a terminal, the token is read from the pipe. Add --json for a JSON result. --api sets the base URL (default https://api.atberth.com/v1).

berth whoami

Calls GET /v1/me. An admin token prints role: admin. An app token prints role: app token.

berth apps list

Lists apps for the admin token. An app token cannot list apps.

berth apps list
berth apps list --json

berth apps create

Creates the app, the database, and a token. The name is the only argument.

berth apps create demo

berth apps delete

Drops that app's database and forgets the saved app token. It does not touch any other database.

berth apps delete demo

berth tables list

Lists tables and columns for one app. --app is required.

berth tables list --app demo

berth tables create

Creates a table. Each column is name:type. At least one column is required.

berth tables create --app demo notes body:text done:boolean

berth rows list

Prints rows, newest first. --limit is optional (default 50, max 200).

berth rows list --app demo notes
berth rows list --app demo notes --limit 10

berth rows add

Inserts one row. Each value is name=value. Use true or false for booleans, and a whole number for integers. Other values are text.

berth rows add --app demo notes body=hello

berth rows get

Reads one row by its uuid.

berth rows get --app demo notes "$ID"

berth rows rm

Deletes one row by its uuid.

berth rows rm --app demo notes "$ID"

Auth

Every request needs a bearer token.

Authorization: Bearer $TOKEN

The admin token can create and delete apps, rotate an app token, and read or write any app. An app token can only use tables and rows for that one app. Base URL: https://api.atberth.com/v1.

Add --json to any CLI command when a script needs JSON. Failures exit nonzero.

Errors

Errors are JSON. There is a short code and one sentence. No stack trace.

{"error":"unauthorized","message":"Send a bearer token."}
  • 400 the name, type, or body is not usable.
  • 401 missing or rejected token.
  • 403 this token cannot do that.
  • 404 that app, table, row, or path does not exist.
  • 409 that app or table already exists.
  • 500 something went wrong on the server.

HTTP API

Admin token:

  • GET /v1/me returns {"role":"admin"}.
  • GET /v1/apps lists apps. No tokens in the list.
  • POST /v1/apps with {"name":"demo"} creates an app. 201. The token is in this response only.
  • GET /v1/apps/demo reads one app.
  • DELETE /v1/apps/demo drops that app database only.
  • POST /v1/apps/demo/tokens rotates the app token and returns the new one once.

App token or admin token:

  • GET /v1/apps/demo/tables lists tables and columns.
  • POST /v1/apps/demo/tables creates a table.
  • GET /v1/apps/demo/tables/notes?limit=50 lists rows.
  • POST /v1/apps/demo/tables/notes inserts one JSON object of column values.
  • GET /v1/apps/demo/tables/notes/{id} reads one row.
  • DELETE /v1/apps/demo/tables/notes/{id} deletes one row.

Names that are not lowercase letters, numbers, and underscore, 2 to 32 characters, starting with a letter, are rejected.