Scripts and CI

Using the CLI in scripts: exit codes, quiet sign-in, and what the CLI does not offer.

The CLI is built for people at a terminal. You can use it in scripts, with some limits you should know.

Use the exit code#

Every command exits with 0 on success, 1 for an access or usage problem, and 2 for a network or service problem.

#!/bin/sh
orvio pull sotto ./vendor/sotto
case $? in
  0) echo "pulled" ;;
  1) echo "check your sign-in and membership" ;;
  2) echo "Orvio is unreachable, try later" ;;
esac

Messages go to the terminal: successes to standard output, failures to standard error.

Sign in on a machine without a browser#

$ ORVIO_NO_BROWSER=1 orvio login

The CLI prints the sign-in link. Open it in a browser and approve.

What the CLI does not have#

• No service token. Sign-in is done by a person, in a browser. There is no key to put in a CI secret.
• No machine-readable output. The CLI prints sentences, not JSON.
• No older versions. Only the latest release can be pulled.

A pattern that fits CI#

1. Pull on your own machine: orvio pull sotto ./vendor/sotto.
2. Commit the files into your private project.
3. Let CI build from your repository.

Rate limits#

If a script makes too many requests in a short time, the CLI prints "Too many requests in a short time." and, when the server says how long, "Try again in N seconds." Exit code 2.

Keep scripts honest#

• Check the exit code, not the text.
• Do not parse the CLI's sentences: their wording can improve.
• Do not use scripts to extract the catalog in bulk. The licence forbids it; normal use of the CLI and the MCP server is allowed.