Command line reference

This is the full text of righto --help for this version of Righto. Install the commands from Righto > Install Command Line Tools…. For a guided start, see Run your books from Claude Code or Codex. For each operation, see Operations reference.

righto: work with your Righto books from a terminal or an AI agent.

Righto serves an unlocked business to agents in one of two ways: the Righto app
with the business unlocked, or "righto serve" with no app window. Each command
signs in with an agent connection. The connection's access level (Read only,
Propose changes, or Full access) applies to every call.

Start with no app:
  righto business create <path.righto> --name <name> --books-start <YYYY-MM-DD>
        [--fiscal-year-start-month <1-12>] [--owner <name>] [--time-zone <TZ>] [--no-password]
                                        Make a new encrypted business file. Righto asks
                                        for a new password (8 or more characters) and
                                        shows the recovery key one time, on stderr.
                                        --no-password: no password and no prompt. Anyone
                                        who can open this computer can read the books.
  righto connections create <name> --file <path.righto> --level READ_ONLY|PROPOSE|FULL
        [--display-name <text>]         Make an agent connection and save its credential
                                        on this computer. The file must not be open in
                                        the app or in righto serve.
  righto connections level <name> --level <level> --file <path.righto>
  righto connections revoke <name> --file <path.righto>
  righto serve <path.righto>            Unlock the file and serve it to agents until
                                        Ctrl-C (SIGINT) or SIGTERM. Then it removes the
                                        socket and locks. If the lock does not finish in
                                        30 seconds (or on a second Ctrl-C), it exits 1.
  righto password change <path.righto> [--recovery-key]
                                        Replace the password. Righto asks for the current
                                        password (or the recovery key), then the new one.
                                        From stdin: line 1 is the current secret, line 2
                                        the new password. The recovery key does not change.
                                        This does not re-key the database: an older copy
                                        of the file still opens with the old password.
  righto recovery-key rotate <path.righto>
                                        Make a new recovery key (asks for the password).
                                        Righto shows it one time, on stderr, never on
                                        stdout. The old recovery key no longer works on
                                        this file (an older copy still opens with it).
  --recovery-key                        Unlock with the recovery key, not the password.

  Righto reads a password or recovery key from a hidden prompt on a terminal,
  or as one line on stdin. Never as an argument or an environment variable.
  A new recovery key (business create, recovery-key rotate) goes only to stderr.
  Password change and recovery-key rotate need the file closed: stop righto
  serve, or close the business in the Righto app, first (exit 3 otherwise).

Learn:
  righto guide                          List the topics of the agent guide (Markdown).
  righto guide <topic>                  Show one topic: how to keep the books with these
                                        commands. Start with getting-started. No connection
                                        is necessary.

Use the books:
  righto status                         Show the connection, business, and access level.
  righto operations                     List every operation. Alias: righto tools
  righto describe <operation>           Show the input schema and an example.
  righto <area> <action> [input]        Run an operation, for example: righto accounts list
  righto query <operation> [input]      Run a read operation by name.
  righto run <operation> [input]        Run a change operation by name.
  righto result <idempotency-key>       Read the stored result of an earlier change.
  righto upload <file>                  Send a local file to Righto and print its uploadId.
                                        Then run imports.seal (a bank statement) or
                                        attachments.attach (a receipt) with that uploadId.
  righto read-scanned <sourceBlobId>    Read the scanned pages of a sealed PDF statement with
                                        on-device OCR in the Righto app (Apple Vision on this
                                        Mac). Prints the uploadId of the text. Then run
                                        imports.seal and imports.preview (format PDF_TEXT,
                                        pdfText.originalSourceBlobId = the PDF).
  righto mcp [--tools full|compact]     Run the MCP server on stdin and stdout.
                                        --tools full (default) lists one tool for each
                                        operation. --tools compact lists only a few tools
                                        (find, describe, query, command), so that the tool
                                        list uses less model context.
  righto connections add <name>         Save a connection credential from the app (read from stdin).
  righto connections list               List the saved connections on this computer.

Input:
  --input '<json>'                      The operation input as JSON.
  --input-file <path>                   Read the input JSON from a file ("-" for stdin).

Upload:
  --media-type <type>                   Default: guessed from the extension (csv, ofx, qfx, pdf, ...).
  --filename <name>                     The name Righto shows. Default: the file's name.

Changes:
  --idempotency-key <key>               Reuse a key to resolve an unknown outcome. Default: a new key.
  --expected-revision <n>               Fail if the business changed since you read revision n.
                                        Default: the current revision at the time of the call.
  --reason <text>                       Recorded in Activity with the change.

Connection:
  --connection <name>                   Use this saved connection.
  --credential-file <path>              Use this credential file (mode 600).
  With no option, Righto uses RIGHTO_CONNECTION (a saved connection name), then
  RIGHTO_CREDENTIAL_FILE, then the only saved connection.

Output is JSON on stdout (righto guide prints Markdown). Exit codes:
  0 ok
  1 service error (also a damaged file, a full disk, or a failed create or open)
  2 usage error (also a used path, a short password, or an unsafe or denied location)
  3 Righto not running or locked, the file is open somewhere else, or Righto already serves agents
  4 access refused (also a wrong password or recovery key)
  5 outcome unknown
Amounts are whole cents as strings ("1250" is $12.50). Dates are YYYY-MM-DD.

More help: https://rightobooks.com/help/ (the same articles as Get help in the app).