Getting started with the CLI

This page assumes you have installed the CLI and have a RestWard account.

Log in

restward login signs in with your RestWard email and password:

restward login --base-url https://api.restward.tech

• --base-url is the platform API address. On RestWard cloud that is https://api.restward.tech; a self-hosted install uses its own API URL. You can set RESTWARD_API_URL instead of passing the flag (RESTWARD_BASE_URL also works).
• In a terminal, the CLI prompts for Email and Password. The password is read with echo turned off and is never printed.
• The password is never passed on the command line, where other processes could see it. Outside a terminal (scripts, CI), pass --email and pipe the password with --password-stdin, or set RESTWARD_PASSWORD - see Using the CLI in CI.
• To use an existing access token instead of a password, run restward login --token and paste or pipe the token.

Login uses the same email and password as the dashboard. Passkey and single sign-on login are not available in the CLI yet.

On success the CLI prints who you are, the organization it selected and the base URL:

Logged in as dev@acme.example
Organization: Acme (6f1c2a8e-3b7d-4c55-9a0e-2d4b8c1f7e90)
Base URL: https://api.restward.tech

Check your session

restward whoami

whoami reads the local config only (it makes no network call) and shows the user, the organization, the base URL, when the session token expires and where the credentials come from (stored session, or RESTWARD_TOKEN when that environment variable is set).

Choose an organization

Every command that talks to the platform acts on one organization. At login the platform scopes your session to your oldest active membership, skipping organizations that require single sign-on, and the CLI selects that organization. If the platform reports none, whoami shows Organization: — and commands fail with No organization selected. restward org list shows all your organizations. To select or switch organizations, pass the organization's slug or ID (a GUID). Both are shown by org list and, with a copy button, on the dashboard's Settings page:

restward org list
restward org use acme
restward org use 6f1c2a8e-3b7d-4c55-9a0e-2d4b8c1f7e90

You can skip org use entirely for one invocation by setting the RESTWARD_ORG environment variable to the organization's ID (a GUID). It overrides the session's organization - the selected one with a stored session, or the token's org_id claim with RESTWARD_TOKEN or login --token - for every platform command in that invocation. It must be a GUID: a slug or typo stops the command with exit 2 (RESTWARD_ORG must be an organization id (GUID).).

Session lifetime

A password login stores the platform's short-lived access token (15 minutes with the platform's default settings) together with a refresh token (7 days). The CLI renews the session transparently: shortly before the access token expires, or once when the platform rejects it, it exchanges the refresh token for a new pair, saves it and retries the request. You only log in again when the refresh token itself has expired or been revoked - the command then fails with Session expired — run 'restward login'.

A session stored with restward login --token has no refresh token: it ends when that token expires.

Log out

restward logout

Logout clears the stored session locally and revokes it on the platform, so a copy of the config file stops working. Your other sessions - the dashboard in your browser, other machines - stay signed in. It works with an expired token; offline it still clears the local session and tells you the session was not revoked. restward logout --everywhere revokes every session of your account instead.

Configuration file

The CLI keeps its state in one JSON file:

Set RESTWARD_CONFIG to use a different file, for example one per project or per CI job.

What is stored:

Your password is never stored. The file is created readable and writable by your user only (mode 0600 on Linux and macOS). It holds live credentials - the refresh token keeps a session alive for days - so never commit or share it.

Next steps

• Connect a database and generate its API
• Command reference