Command reference

restward <command> [options]

Run restward --help for the command list and restward <command> --help for one command's options.

Global options

These work with every command, anywhere on the command line.

Options that take a value accept both --name value and --name=value.

JSON output

With --json, stdout carries exactly one JSON object, the result envelope:

{ "success": true, "value": { "email": "dev@acme.example" } }

{ "success": false, "error": "Not logged in. Run: restward login --base-url <url>" }

In JSON mode, errors are written to stdout as the envelope, progress lines are suppressed, and prompts (which go to stderr) still appear when running in a terminal. The shape of value for each command is listed below.

Exit codes

login

Log in with email and password, and store the session in the config file.

restward login [--base-url <url>] [--email <email>] [--password-stdin] [--token] [--web] [--no-browser]

The password is taken from, in order: --password-stdin; a prompt without echo when running in a terminal; the RESTWARD_PASSWORD environment variable (last resort).

A password login stores an access token and a refresh token. The CLI renews the session transparently: shortly before the access token expires, or once after the platform rejects it, it exchanges the refresh token for a new pair and retries the request once. When that is not possible the command fails with Session expired — run 'restward login'.

--web / --no-browser (web-brokered sign-in): the /cli/authorize page shows the machine name, the CLI version and a match code that must match the one printed in the terminal; approving mints a single-use, 60-second code. The CLI exchanges it for its own session (access + refresh token) with PKCE S256 — the code is bound to the loopback port and hostname, and a callback with a mismatched state is ignored: only the genuine callback completes the sign-in, and a denial in the web page cancels it. The same session storage is used as for a password login.

JSON value: email, organizationId, organizationName, baseUrl, expiresAt.

password

Manage the account password. restward password change changes it for the signed-in account; the platform then revokes every session of the account and re-issues the current one, which the CLI stores as the new session.

restward password change [--password-stdin] [--new-password-stdin]

The current password is taken from, in order: --password-stdin; a prompt without echo when running in a terminal; the RESTWARD_CURRENT_PASSWORD environment variable (last resort). The new password: --new-password-stdin, a prompt without echo, RESTWARD_NEW_PASSWORD. Both never come from the command line.

Before the new password is submitted the platform rule is printed (12 to 256 characters, no common or breached password, not the email address or the organization name), and the length is checked locally before any request goes out. The full rule - including the common-password list

• is enforced by the platform and reported in the error when it fails.

When a login shows that the stored password no longer meets the rule, the session is still stored and the output points here: restward password change.

logout

Clear the local session (access and refresh token) and revoke this session on the platform, so a copy of the config file can no longer be renewed. Other sessions - the browser, other machines - stay signed in. The revocation needs no valid access token, and when the platform cannot be reached the local session is cleared anyway (the output says the session was not revoked).

restward logout [--everywhere]

Fails (exit 1) when there is no session to clear, or when --everywhere could not reach the platform (the local session is cleared anyway). A plain logout that cannot reach the platform succeeds (exit 0), clears the session locally and says the session was not revoked; it then expires on its own after at most 7 days. Settings in the config file that are not part of the session are kept.

JSON value: revokedEverywhere, revokedSession (this session was revoked on the platform).

sessions

List the signed-in user's active session families - every CLI and web session, in any organization - and revoke one. The current session (the one this CLI's session belongs to) is marked with *. Revoking a session signs that device out; revoking the session this CLI is signed in with also clears the local credentials, exactly like logout (the output says the session was signed out on this machine). A family id that is not the caller's - or does not exist - is refused by the platform with a 404, and the command prints No such session (no existence oracle).

restward sessions [list] | sessions revoke <familyId>

list shows each family's short id, start time, last refresh, method (amr), client (cli or web), organization id, and the current-session marker. JSON value: sessions (the full family list); for revoke: revoked, familyId, signedOutHere (the local session was cleared).

whoami

Show the logged-in user, organization, base URL, token expiry and where the credentials come from (RESTWARD_TOKEN or the stored session). No network call.

restward whoami

JSON value: email, organizationId, organizationName, baseUrl, tokenExpiresAt, authSource.

org

List your organizations, or select the organization that later commands act on.

restward org list | org use <orgId|slug>

With a session from restward login (email and password), org use switches the session on the platform before saving the selection. The platform refuses the switch, and nothing changes locally, when you have no active membership in that organization, or when the organization requires single sign-on and you are not an administrator there. With a token from RESTWARD_TOKEN or login --token, org use only changes the local selection.

A per-invocation alternative to org use: set RESTWARD_ORG to an organization id (a GUID). It overrides the session's selection - the org use choice for a stored session, or the token's org_id claim for a RESTWARD_TOKEN / login --token session - and makes every platform command in that invocation act on it. It must be a GUID, not a slug: an invalid value stops the command with exit code 2 (RESTWARD_ORG must be an organization id (GUID).).

JSON value: org use: organizationId, organizationName (set when a slug was given). org list: currentOrganizationId, memberships (organizationId, organizationName, role, status).

connect

Connect a database and generate its REST API in one step: create the connection, test it, read the schema, create and provision the API, and issue an API key. See Connect a database for connection-string formats and the full flow.

restward connect <name> [--connection-string <cs>] [--provider <p>] [--database <db>] [--no-ssl] [--server-certificate <file>] [--client-wallet <file>] [--timeout <s>]

JSON value: connection (id, name, provider, host, port, database, tableCount, columnCount), api (id, name, slug, status, endpoint), key (id, name, prefix, plaintext, role), endpoints, docs.

list

List the organization's database connections and generated APIs.

restward list

Shows each connection's name, provider, status, table count and last sync time, and each API's name, slug, status and endpoint URL.

JSON value: connections, apis.

keys

List the API keys of a generated API, create one, change its IP allowlist, revoke it, or rotate it. Keys are redacted to their stored prefix: the full key is shown only once, when it is created or rotated.

restward keys [--api <slug-or-id>] [list] | keys create --name <name> [--allowed-ips <list>] | keys allowed-ips <key> (--set <list> | --clear) | keys revoke <key> [--yes] | keys rotate <key>

Lists each key's name, prefix, role, rate limit per minute, allowed IPs (any when unrestricted), expiry and status (active or revoked). Entries are addresses (203.0.113.7) or CIDR ranges whose address is the network address (203.0.113.0/24; 10.1.2.3/8 is refused); the platform names a refused entry. A change applies to the running API within 30 seconds. See API keys & tenant API auth.

JSON value: api (id, name, slug), keys; for create: key (id, name, plainTextKey, allowedIpRanges, role); for rotate: key (id, name, key, maskedKey); for allowed-ips: key; for revoke: revoked, keyId, keyName.

api

restward api refresh <slug-or-id> [--org <orgId>] [--wait] [--timeout <seconds>]

Requests a database schema re-read and route rebuild on the runtime's next poll (normally within 30 seconds, plus reflection time). Automatic schema refresh is off by default; this command works independently of that setting.

Requires a current Contributor, Administrator, or SystemAdmin membership. Use the usual stored login or RESTWARD_TOKEN, RESTWARD_API_URL, and RESTWARD_ORG_ID for automation. Tenant data-plane API keys do not authenticate control-plane commands.

# CD: apply a migration, then wait for the runtime to read the updated schema.
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f migration.sql
restward api refresh orders --wait --timeout 180

In configured mode, a new table also needs generated, enabled endpoint policies (Generate Endpoints in the dashboard, or the control-plane regenerate endpoint). Refresh alone never grants access to a table with no policy. Pending triggers within 60 seconds are coalesced only before reflection starts; a trigger during an in-flight read queues a subsequent read. Repeated calls after completion always request a new read.