CLI¶
osh is a command-line interface for Odoo.sh, in the spirit of gcloud, aws and scw. It is
built on the odouche library and adds nothing of its own beyond presentation:
every command is a call into the library, rendered for a terminal.
This page is the guide. The reference has every command with its arguments,
options and defaults, as osh <command> --help prints them.
Install¶
To run it once without installing it:
Sign in¶
- A browser window opens for you to sign in to Odoo.sh with GitHub.
oshstores the session in your operating system's keyring and names the account. Where no browser can be launched, as over SSH, it asks for thesession_idcookie in a prompt that does not echo it. - Security has what is kept, where and for how long.
osh auth statusshows where the session comes from, how long ago it was stored and when it expires. It exits 3 when there is no usable session, so a script can test for one.osh auth logoutremoves the session from the keyring and says whether Odoo.sh ended it.- No option takes a session: arguments show in the process list and in the shell history. Where
there is no keyring, as in CI, the session comes from
ODOUCHE_SESSION.
Push, watch, read the logs¶
From a checkout of the repository that the project acme builds, on the branch feature-x:
-
osh builds watchwaits for the build of the commit you pushed, follows it until it finishes and exits with its result. Its last line is the result and the address of the build's database: -
osh logsprints the end of that build'sinstalllog, where a development build installs the modules and runs their tests. A build that has none, as on a staging branch, gives itsodoolog.osh logs --followkeeps printing while the build runs. - As one line:
git push && (osh builds watch || osh logs). - Anywhere else, name the two:
osh builds watch --project acme --branch feature-x. osh builds rebuild --watchstarts a new build of the branch without a commit, and watches it.
Project and branch¶
A command that works on a project or a branch takes them from the first of these that gives a value:
| Order | Project | Branch |
|---|---|---|
| 1 | --project |
--branch |
| 2 | OSH_PROJECT |
OSH_BRANCH |
| 3 | The git checkout's remote, when it is a GitHub repository | The git checkout's current branch |
- The project is given by its name, as
osh projects listshows it. - The remote is the upstream of the current branch, and
originotherwise. A detached HEAD gives no branch. - A repository that several of your projects build is never guessed between: the command exits 2 and lists them. One that none of them builds exits 4.
- With no source giving a value, or an empty
--projector--branch, the command exits 2. --debugsays on stderr which source was used.
A project's overview¶
osh projects show prints the project's overview, one fact per line: its
subscription, Odoo version, region, storage of its quota, workers, staging branches, whether it is
on a dedicated server, its production build, its branches by stage and your access to it.
- Storage, workers and staging branches are on the project's Settings page, which Odoo.sh shows
to an admin of the project only. Anyone else gets
admins onlyin the table, and"hosting": nullin the JSON. The region is shown to every member. - It asks Odoo.sh what the project's page and its Settings page ask: the project's info, its branches and, for an admin, its settings, and the projects for the region. It changes nothing.
- A subscription state
oshdoes not know is printed as Odoo.sh names it.
A project's settings¶
osh projects settings show prints the project's settings, one per line,
as its Settings page has them: the odoo.com domain block, the session lifetime, public access,
commit statuses, the deploy key, private submodules, storage, workers, staging branches, dedicated
hosting and its timeouts, the defaults of new development branches, and the IP allow list.
osh projects settings show
osh --format json projects settings show --project acme-shop | jq .ip_allow_list
- Odoo.sh shows the settings to an admin of the project only. Anyone else exits 5, and the settings are not asked for.
- The table gives the timeouts in minutes, as the page does, and a submodule as its URL and the fingerprint of its deploy key. The JSON gives the timeouts in seconds and each submodule's public deploy key too.
- A submodule URL is shown without its query, its fragment and its credentials, or as
nonewhen it cannot be read safely, as the library has it. Every token and code Odoo.sh sends with the settings is dropped unread. - An allowed entry is shown as written, an address or a network. A setting whose value
oshdoes not know, or an allowed entry that is neither an address nor a network, exits 6. - It changes nothing on Odoo.sh.
Changing a project's settings¶
osh projects settings set changes the settings of a project you are an
admin of, and only those given that differ: the others keep their value. It takes NAME=VALUE as
osh branches settings set does, named and valued as osh projects
settings show --format json prints them, and the IP allow list by entry:
osh projects settings set ai_agent=opencode demo_data=no
osh projects settings set --add-ip 203.0.113.7 --remove-ip 198.51.100.42
- Every value is checked before anything is asked of Odoo.sh: an unknown name or value exits 2.
--add-iptakes an IPv4 address and--remove-ipan address or a network asshowlists it, each as many times as needed.ip_allow_list=exits 2: the list is never replaced whole. - A timeout is in seconds, a whole number of minutes within the bounds of the Settings page, and is changed on a dedicated server only. Both timeouts are sent, as the page sends them, the other with its value as read. The defaults of new development branches follow the rules of a branch's new build options. The list holds ten entries at most. Each exits 2 before the question.
- It first says on stderr the project and each setting from its value to the new one, the list included. An address already allowed, or an entry not in the list, is said and left out. With nothing to change it sends nothing and exits 0.
- A change to the allow list, public access or the session lifetime changes who can reach the
project: a line says so, and the question asks to change access. SSH from a removed entry then
needs the one-hour rule
osh sshasks for, PostgreSQL on a dedicated server is closed to it, and an emptied list is said too. oshcannot tell the address you reach Odoo.sh from without allowing it, so it does not refuse a change that removes yours. The list covers SSH, and PostgreSQL on a dedicated server, to production and staging: the web page andoshkeep working, andosh sshcan still allow your address for SSH for an hour.- The list is rebuilt from a read made just before the change, so an edit made elsewhere in between is overwritten, as it is by the page.
- It asks and takes
--yesas a rebuild does, and exits 5 for a user who is not an admin of the project. The rest is as for a branch: one request, the settings read back shown, a setting Odoo.sh moved along said, and exit 10 when Odoo.sh does not confirm the change. - The project's name, the
odoo.comdomain block, the deploy key, the commit statuses, submodules and anything billed are not changed byset.
Checking a project¶
osh projects check reads the project's overview, as osh projects show
does, and judges four facts of it. It prints one row per check: its name, its result (pass,
warn, fail or skip) and the fact it was judged on. It exits 30 when a check fails, 31 when
none fails and one warns, and 0 otherwise.
osh projects check || case $? in
30) echo "Something is broken." ;;
31) echo "Something needs a look." ;;
*) exit $? ;;
esac
| Check | Fails | Warns |
|---|---|---|
subscription |
Expired, or in a state osh does not know, which the project's page calls invalid. |
A trial, a non-standard subscription, or a valid one with trial days left. |
production |
The last build of a production branch failed. | No production branch, one with no build, or a last build that is running or ended without a result, finished with warnings, or has a result osh does not know. |
storage |
The storage used is at or over the quota. | The storage used is within --storage-margin percent of the quota: 10 by default. 0 never warns and 100 warns on any use. |
branches |
The last build of any branch, production included, failed. | The last build of a branch has a result osh does not know. |
- A build dropped for a newer one is judged by the result it had.
- Storage is on the project's Settings page, which Odoo.sh shows to an admin of the project only.
Anyone else gets
skipwithadmins only. A quota of 0 isskiptoo, with the storage asosh projects showprints it. Askipdoes not count in the exit code. - The check names are what a script matches on.
osh --format json projects checkgives the same rows and exits as the table does. Piped intojq, the pipeline exits withjq's code unless the script runsset -o pipefailor reads${PIPESTATUS[0]}. - It changes nothing on Odoo.sh.
A project's audit log¶
osh projects audit lists the project's audit log, newest first: the date
in UTC, who did it, the stage, or project for an action on the project, the action and what
Odoo.sh adds about it.
osh projects audit --limit 10
osh projects audit --since 2026-10-01
osh --format json projects audit --project acme-shop | jq '.[] | select(.kind == "download_database")'
- Odoo.sh shows the log to an admin of the project only. Anyone else exits 5, and the log is not asked for.
- Odoo.sh sends the whole of the last 30 days in one answer, with no paging.
--limit, 20 by default and 200 at most, and--sincebound what is printed, not what Odoo.sh sends. Nothing older than 30 days can be read, whatever--sincesays. --sincetakes a date,2026-10-01, or a time,2026-10-01T09:30:00, in UTC.--limitapplies first: when it leaves out entries since that date, a line on stderr says so.- An action
oshdoes not know is printed as Odoo.sh names it, and one that failed is followed by(failed). The author and the details are printed without control characters. - It changes nothing on Odoo.sh.
A project's members¶
osh projects members list lists the project's members: each one's GitHub
login, the name Odoo.sh gives them, their role, and whether they have logged in to Odoo.sh yet.
Admins come first, then testers, then developers, each by login.
osh projects members list
osh --format json projects members list | jq '.[] | select(.role == "admin") | .login'
- Odoo.sh shows the members to an admin of the project only. Anyone else exits 5, and the settings they are part of are not asked for.
Logged inisnofor a member who was invited and has not logged in to Odoo.sh yet.- The JSON adds the membership's
idand the member's GitHub user number,github_id. Odoo.sh gives no member's email. - A login and a name are printed on one line without control characters. A role
oshdoes not know exits 6. - It changes nothing on Odoo.sh.
Changing a project's members¶
osh projects members add adds a GitHub user to the project's members, and osh projects members
role gives a member another role, developer, tester or admin:
- An admin reaches production: its database, shell and logs, and the project's settings. A tester reaches staging, not production, and a developer development branches only. Only an admin of the project changes its members: anyone else exits 5.
addtakesdeveloperunless--rolesays otherwise, as the page does. Odoo.sh sends the new member no invitation, and push access to the repository is given on GitHub, not byosh.addtakes a login as GitHub takes one for a new account: 1 to 39 letters, digits and single inner hyphens. Any other exits 2 before a request; an older login that breaks the rule is added in the page. The login is looked up on GitHub through Odoo.sh, as the page's search does, and must match exactly: otherwise the command exits 4.- The lookup needs Odoo.sh's grant on GitHub to cover private repositories. When it does not, the command exits 5: search a GitHub user once in the Collaborators item of the project's Settings page, which asks GitHub for it, then run it again.
roletakes a login aslistprints it, in any case. One that is not a member exits 4, and a member who already has the role exits 0 with nothing sent.- Both read the members first. Adding someone already a member, by login or by GitHub number under a login since renamed, exits 9 with nothing sent, as does lowering the last admin who has logged in to Odoo.sh: give another member the admin role first.
- Each first says on stderr the project, the member and the role, from the old one for
role, and what the role reaches. An admin lowering their own role is told they will not be able to change it back. It asks, and takes--yesin a script, as a rebuild does. - The change is sent once, then the members are read back and the member is shown as
listshows them. When Odoo.sh does not confirm it, or the member does not read back with the role, the command exits 10: look withosh projects members list. - No MCP tool adds a member or changes a role, with or without
--allow-changes.
Watching a build¶
osh builds watch follows one build until it finishes: the one whose number is given, or the
build of the commit you just pushed.
- When the checkout is of the project's repository and on the branch, however the two were named, it waits for a build of the checkout's HEAD to be listed, asking every 3 seconds, and watches that one.
--commitwaits for another commit of the branch, also when the branch is not the one checked out.--no-waitwatches the branch's latest build, whatever its commit, and so does a run with no--commiton another project or branch than the checkout's, or one where HEAD cannot be read.- The wait for a commit's build lasts two minutes at most, then exits 23: push the commit, or use
--no-wait.--timeoutcovers that wait and the build. - The changes go to stderr: one line kept up to date when stderr is a terminal, with how long the build has run, and one line per change otherwise. The last line, on stdout, is the result and the address of the build's database.
- A build that was dropped after it finished exits with the result it had, and is said to have been replaced by a newer build. A dropped build has no address.
- Ctrl+C exits 130 and leaves the build running: watching changes nothing on Odoo.sh.
Rebuilding a branch¶
osh builds rebuild starts a new build of the branch, which replaces its latest one. It is one
of the commands that change a project, with
osh branches settings set,
osh branches move,
osh projects settings set,
osh projects members add and role, osh backups create,
osh backups download, and osh ssh and
osh backups pull when they allow your address. Every other command
that opens a client opens it read-only, and it sends no change.
- Only a development or a staging branch is rebuilt. Any other stage exits 9 before anything is asked or sent.
- It first says on stderr what it works on: the project, the branch with its stage, and the
branch's latest build with its commit. Then it asks on stderr, and anything but
yoryessends nothing and exits 1. --yesrebuilds without asking. When stdin or stderr is not a terminal it is required: without it the command exits 2 and sends nothing. In a script:osh builds rebuild --yes --watch.- Once the rebuild is sent, stderr names the new build. It is then shown as
osh builds showshows one. --watchwatches the new build asosh builds watchdoes, with that command's output and exit codes.- A watch that fails leaves the build as it is: stderr names it, for
osh builds watchto follow. Anotherrebuildwould start a second build. - The rebuild is sent once. When Odoo.sh does not confirm it, or the new build is not found, the
command exits 10: look at
osh builds listbefore running it again, since a second rebuild can start a second build.
Changing a branch's settings¶
osh branches settings set changes the settings it is given, as NAME=VALUE, and only those: the
others keep their value. The names and the values are those osh branches settings show --format
json prints, a yes or no is yes or no, and modules takes names separated by commas:
osh branches settings set --branch feature-x ai_agent=opencode
osh branches settings set --branch feature-x project_defaults=no module_install=listed modules=sale,stock
- Every value is checked before anything is asked of Odoo.sh: an unknown name or value exits 2.
- What a new commit does,
push_behavior, is not changed on a production branch, and the new build options only on a development branch: either exits 9 before anything is asked or sent. While the project's defaults apply, an option is changed withproject_defaults=nobeside it, and without it the command exits 2. - It first says on stderr the project, the branch with its stage, and each setting from its value
to the new one, or that it already has it. With nothing to change it sends nothing and exits 0.
Otherwise it asks, and takes
--yesin a script, as a rebuild does. - The settings that differ are sent once, in one request. The settings read back are then shown as
osh branches settings showshows them. Another setting Odoo.sh changed along with them, such as the tests once every module is installed, is said on stderr, from its value to the new one, as also changed by Odoo.sh. - When Odoo.sh does not confirm the change, or a setting sent does not read back as sent, the
command exits 10: look with
osh branches settings show. Sending the same change again does no harm. - The Odoo version and revision, the operating system and the custom domains are not changed by
set.
Moving a branch between stages¶
osh branches move --to staging moves a development branch to staging, and --to development
moves a staging branch back:
- A move to staging starts a build of the branch on a copy of production's data, with outgoing mails caught and scheduled actions turned off, and its next commits build the same way. A move to development drops the branch's staging builds, which are not backed up.
- The production branch is not moved, and no branch is moved to production: that is done in the
Odoo.sh page.
--to productionexits 2. A production branch, or one already in the stage asked, exits 9 and sends nothing: before the question whenosh branches listalready shows it, otherwise once the stage is read again just before the move. - It first says on stderr the project, the branch with its stage, the move, and what Odoo.sh does
to the branch. It asks, and takes
--yesin a script, as a rebuild does. - The move is sent once, then the branch is read back and shown as
osh branches listshows it. After a move to staging, stderr namesosh builds watchto follow the new build. - When Odoo.sh does not confirm the move, or the branch does not read back in the new stage, the
command exits 10: look with
osh branches list. Running the move again is refused once the branch is there.
Taking a backup¶
osh backups create asks Odoo.sh for a manual backup of the branch's latest build, which Odoo.sh
keeps for 3 days. It asks first, and takes --yes in a script, as a rebuild
does.
- Only a staging or a production branch is backed up. Any other stage exits 9 before anything is asked or sent. A backup has only been observed on staging.
- It first says on stderr the project, the branch with its stage, the latest build, and that the
backup is kept for 3 days. Anything but
yoryessends nothing and exits 1. --commentis kept with the backup, as the page's dialog asks.- Odoo.sh answers nothing about the backup, which it lists about a minute later. Without
--waitthe command says so and ends. With--waitit asks Odoo.sh every five seconds until the backup is listed and finished, then shows it asosh backups listdoes.--timeoutbounds the wait, 600 seconds by default; past it the command exits 8, and the backup may still come. - The request is sent once. When Odoo.sh does not confirm it, the command exits 10: look at
osh backups listbefore running it again, since a second request takes a second backup.
In a script: osh backups create --branch staging --yes --wait.
Downloading a backup¶
osh backups download has Odoo.sh prepare a backup's file, then writes it to the path --output
names. The file is a zip of the database, as dump.sql, and of its filestore. It is customer data:
it is created readable by its owner alone (mode 600), it is never written over an existing file,
and deleting it once you are done is yours to do.
BACKUPis the time that names the backup, in UTC, asosh backups listshows it, quoted:"2026-10-14 12:48:50". Without it, or withlatest, it is the branch's newest backup that can be downloaded. Aremotebackup cannot be: download thedailyone of the same time.--outputor--linkis required, so the file never lands somewhere you forget it holds a database. Without either, the command exits 2 before asking Odoo.sh anything.- The database is neutralized, as the page offers it first.
--exactasks for the real one, and--no-filestoreleaves the filestore out. Only the neutralized one with its filestore has been observed. - Preparing the file changes state on Odoo.sh, so the command asks first and takes
--yes, as a rebuild does. It then waits for Odoo.sh to say the file is ready, which took 30 seconds for a small database, up to--timeout(600 seconds by default; past it, exit 8). Odoo.sh keeps a prepared file for 2 hours. - When Odoo.sh already holds the file of that backup, prepared with the same choices and still
there, the command takes it: no question, no preparation and no wait. With no terminal,
--yesis still required, so a script does not depend on what Odoo.sh holds. - A download that fails or is interrupted removes the partial file.
--linkprints the page's link to the prepared file on stdout instead. It opens only in a browser signed in to Odoo.sh, and grants nothing to anyone else.--newtakes a backup of the branch's latest build first, waits for it, and downloads it, with one question for both. It never takes a file Odoo.sh holds.- When Odoo.sh does not confirm the preparation, the command exits 10. Preparing the file again does no harm.
In a script: osh backups download --branch staging --new --yes --output staging.zip.
Copying a backup over SSH¶
osh backups pull copies a backup's SQL, gzipped and without the filestore, from the production
build with your own rsync, or scp without it. Odoo.sh prepares nothing: the production build
keeps the latest daily backup of production, and the manual backups of every stage, in
~/backup.daily. osh reads no key, and its process becomes rsync or scp, so the exit code is
then theirs.
- It always connects to the production build, whatever is checked out.
--branchnaming another stage exits 2 before anything is tried. - Without
--manualit copies the daily backup.--manualtakes the time of a manual backup, in UTC, asosh backups listshows it, quoted:"2026-10-14 12:48:50". --outputis required, and is never written over. The file is customer data, created readable by its owner alone (mode600); deleting it is yours to do.- An address not allowed is handled as
osh sshdoes it, on the production branch, with--yesto allow without asking. - Where there is no
rsync,scporssh, as on native Windows, the command to run by hand is shown andoshexits 14.
In a script: osh backups pull --yes --output daily.sql.gz.
Reading a log¶
A log is untrusted text, and osh logs writes it to stdout only: nothing of a log goes to
stderr, with --debug or without.
- On a terminal the escape sequences and control characters are removed from each line, tabs
kept, so a line cannot clear the screen or set the window's title. When stdout is a pipe or a
file the lines are written as they are.
--stripand--no-stripforce one or the other. - A line longer than 64 KiB is cut, and bytes that are not UTF-8 are replaced. A character
stdout cannot encode is written as its escape, such as
\u2192. - Each line is flushed as it is printed. When the pipe it is written to closes, as under
osh logs | head, the command ends with nothing on stderr and exits 141. --followasks Odoo.sh for new lines every second, until Ctrl+C, which exits 130.--kindslists the logs the build has: the kind, what Odoo.sh calls the log, its size and how long ago it was last written to. A kindoshdoes not know isunknown, and--kindtakes its name. A build that waits for a worker has no log yet.- A log the build does not have exits 4, and the message names the ones it has.
Reading a build's mails¶
A development or a staging build sends no mail: Odoo.sh catches each one. osh builds mails
lists those of the branch's latest build, or of BUILD_ID, newest first, and --mail shows one
with its body:
osh builds mails --branch staging
osh builds mails 88212 --branch staging --limit 5
osh builds mails --branch staging --mail 1761213600.M1P1Q1.build
- A mail is untrusted text: the build's code or its data wrote it. Its headers and its body are printed without escape sequences, control characters and bidirectional controls, tabs kept, on a terminal or not.
- An HTML body is printed as text. Nothing in it is rendered, opened or fetched, and there is no
--open. - With
--format json, a mail is printed as its model, which JSON escapes. - A body over 1 MiB, a header over 65536 characters and a mail of more than 1000 MIME parts, containers included, are cut, and a mail over 16 MiB is shown without its body or attachments. Either says so on stderr.
- A build that caught nothing says so on stderr and exits 0. A production branch exits 4, and so does a mail the build did not catch.
A shell on a build¶
osh ssh opens a shell on the latest build of the branch, with your own
ssh: its configuration, its agent and the keys registered on your Odoo.sh account. osh reads
no key, and its process becomes ssh, so the exit code is then ssh's.
- The options of
oshcome first. Everything from the first argument on is given tosshafter the host: a command to run on the build, or options ofssh. Put--before it when it starts with a dash:osh ssh -- -L 8069:localhost:8069. - A build with no address exits 4.
- Odoo.sh lets a build be reached only from an allowed address.
oshfirst runstrueon the build with yoursshin batch mode, which asks for nothing. When that does not get in,oshoffers to allow the address Odoo.sh sees from your machine for one hour: the "Allow my IP" of the branch's page, which was seen to open other branches of the project too. Declining exits 1.--yesallows without asking, and is needed when stdin or stderr is not a terminal: without it,oshexits 2. - Once allowed,
oshtries again every ten seconds for up to ten minutes, then becomesssh. Past that it exits 8, with the last linesshprinted. - The try checks no host key, since every build is a new name for the gateway's key: the
sshoshbecomes asks you about it. When the build refuses your keys (Permission denied), the address got through:oshsends nothing and becomesssh. - Where there is no
sshto become, as on native Windows, the command to run by hand is shown andoshexits 14.
A build's panels¶
osh builds open PANEL prints the URL of the monitor, the shell or the editor of the latest build
of the branch, or of BUILD_ID, as the branch's page links to them. It asks
Odoo.sh only for the branch and its builds, and changes nothing.
osh builds open shell --branch staging
osh builds open editor 1234 --open
osh builds open monitor --branch main --open
--opensends the URL to your default browser instead, and says on stderr which panel of which build it sent. The browser signs in to Odoo.sh on its own:oshhands it the URL and nothing else. Where no browser can be started, the URL is printed for you to open andoshexits 14.- A build has panels once its status is
done. One still in progress, waiting for a worker included, exits 4. - The monitor is the branch's, and shows its latest build: it takes no BUILD_ID (exit 2), and only a staging or a production branch has one (exit 4).
- The shell and the editor are on the build's own host, which takes the Odoo.sh login of the browser too.
Scripts¶
Output¶
--format table (the default) or --format json, given before the command. Only the result is
written to stdout, so osh --format json ... | jq receives nothing else.
-
JSON is the whole model of the library, and its keys are the model's attribute names in the API reference. Datetimes are ISO 8601 with an offset.
Command JSON on stdout osh auth statusOne SessionInfo.osh auth status --checkOne Identity, with theSessionInfoas itssession.osh projects listAn array of Project.osh projects showOne ProjectOverview.osh branches listAn array of Branch, in the order of the table.osh branches historyAn array of Tracking, newest first, whatever--commitssays.osh projects settings show,osh projects settings setOne ProjectSettings: after the change, forset.osh branches settings show,osh branches settings setOne BranchSettings: after the change, forset.osh branches revisionOne BuildRevision. Submodule commits are not in it, and a line on stderr says they are not available.osh backups listAn array of Backup, newest first.osh backups create --waitOne Backup. Without--wait, nothing.osh builds listAn array of Build.osh builds show,osh builds rebuildOne Build.osh builds openThe URL, as a JSON string. With --open, nothing.osh builds watch,osh builds rebuild --watchOne Buildper line, for each change, the first being the new build after a rebuild. The result line goes to stderr.osh logsOne LogLineper line.osh logs --kindsAn array of Log. -
These commands print JSON of
osh's own, which is on one line but forosh projects check:Command JSON on stdout osh projects checkAn array of the checks: name,result(pass,warn,failorskip) andfact.osh auth loginidentity: theIdentityof the stored session, ornullwhenODOUCHE_SESSIONis set.osh auth logoutsource: where the session came from, ornullwith none.deleted: whether it was removed from the keyring.invalidated: whether Odoo.sh ended it.failure: why Odoo.sh could not be asked, ornull.osh --versionoshandodouche: the version of each. -
An empty result is
[]as JSON, and one line on stderr as a table. Both exit 0. - A table has no colour and no box drawing when stdout is not a terminal or
NO_COLORis set. The result of a build is coloured on a terminal, and always written out. - A table shows times as how long ago they were, except the time that names a backup, which is shown in UTC. JSON has the time itself.
- A stage, a status or a result
oshdoes not know is shown as Odoo.sh names it. - A table has the control characters removed from every cell, and a tab or a line break made a
space, so a commit message cannot drive the terminal. JSON has them escaped, in a
LogLinetoo, so--striphas no effect on it. The lines ofosh logskeep them when stdout is not a terminal.
Exit codes¶
A command that fails prints one or two lines on stderr, what happened and what to do, and nothing on stdout. These commands do otherwise:
osh builds watch, andosh builds rebuild --watchlike it, exits non-zero for a build that did not succeed, with the result line on stdout, or on stderr as JSON.osh builds listandosh builds showexit 0 whatever the build's result.osh logscan fail after lines went to stdout, at a follow's timeout (8) or when a request fails (7).osh builds open --openprints the URL on stdout when no browser can be started, and exits 14.osh projects checkprints its checks on stdout when it exits 30 or 31.osh ssh, once it has becomessh, exits with whatsshexits with: the code of the remote command, or 255 for an error ofsshitself. The table below is not how to read it.
| Code | Meaning | Returned by |
|---|---|---|
| 0 | Success. osh auth logout with nothing to log out of is one. |
Every command |
| 1 | Unexpected error, which is a bug to report, or a prompt or a question that was declined. | Every command |
| 2 | Usage error: an unknown option, a value an option does not take, options that do not go together, no project or branch, a download with neither --output nor --link, or to a file that exists or a directory you cannot write to, a rebuild, a move, a backup, a download, a change of settings or members or an IP allow that cannot be confirmed, a login GitHub would not take, a role that is not one, or a setting a branch's Settings tab or a project's Settings page does not let you change with the others as given. |
Every command |
| 3 | No session, or an expired one. Run osh auth login. |
Every command that needs the session |
| 4 | The project, branch, build, backup or log is not one the logged-in user can reach. A build that is not among the branch's latest ones is not, and neither is the build of a branch that has none, a backup that cannot be downloaded, a build with no panels yet, the monitor of a development branch, a mail the build did not catch, or the mails of a production branch. A login that is not a member, or that GitHub does not have, is not either. | Every command that takes a project |
| 5 | The session is not allowed to do this, or Odoo.sh's grant on GitHub does not cover the search of a user. | Every command that asks Odoo.sh |
| 6 | Odoo.sh answered in a shape osh does not read. Please report it. |
Every command that asks Odoo.sh |
| 7 | Odoo.sh could not be reached, or answered with a server error. | Every command that asks Odoo.sh |
| 8 | A followed log, a login, a project's audit log, or a backup's or a download's wait reached its timeout, or ssh did not get in once the IP was allowed. |
osh logs --follow --timeout, osh auth login, osh projects audit, osh backups create --wait, osh backups download, osh ssh |
| 9 | Refused, and nothing was changed: a read-only run, or a branch in a stage osh does not change, or a setting its Settings tab does not offer in that stage, or a move to the stage a branch is in, or a user added who is already a member, or the last admin lowered. |
osh builds rebuild, osh branches settings set, osh branches move, osh projects members add, osh projects members role, osh backups create, osh backups download --new |
| 10 | A change was sent and Odoo.sh did not confirm it. osh builds list shows whether a build was started, osh backups list whether a backup was taken, osh branches settings show or osh projects settings show whether the settings were changed, osh branches list whether a branch was moved, osh projects members list whether a member was added or given the role; osh ssh, osh backups download, either settings set and osh projects members role can be run again. |
osh builds rebuild, osh branches settings set, osh projects settings set, osh branches move, osh projects members add, osh projects members role, osh backups create, osh backups download, osh ssh |
| 11 | No usable keyring: none to store the session in, or one that stayed locked. | osh auth login, osh auth logout, every command that reads the stored session |
| 12 | The login ended without a session. | osh auth login |
| 13 | Any other error from the library. | Every command |
| 14 | No ssh to hand over to, or native Windows, or no browser could be started. The command to run, or the URL to open, is shown. |
osh ssh, osh builds open --open |
| 15 | The disk refused the file: full, or no longer writable. Nothing of it is left. | osh backups download |
| 20 | The build failed. osh logs is the next step. |
osh builds watch, osh builds rebuild --watch |
| 21 | The build finished with warnings. | osh builds watch, osh builds rebuild --watch |
| 22 | The build ended without a result. It was dropped for a newer build, killed or skipped, or its result is one osh does not know. |
osh builds watch, osh builds rebuild --watch |
| 23 | The build had not finished, or had not appeared, at the timeout. | osh builds watch, osh builds rebuild --watch |
| 24 to 29 | Reserved for the result of a build. | None yet |
| 30 | A check of the project failed. | osh projects check |
| 31 | A check of the project warned, and none failed. | osh projects check |
| 32 to 39 | Reserved for the result of a check. | None yet |
| 130 | Interrupted with Ctrl+C. | Every command |
| 141 | Stdout is a pipe and its reader, such as head, closed it. Nothing is written to stderr. |
Every command |
--debug, or OSH_DEBUG=1, adds the traceback on stderr. It shows no local variables, and a
session supplied through ODOUCHE_SESSION is masked in it.
Environment variables¶
| Variable | What it does | Read by |
|---|---|---|
ODOUCHE_SESSION |
The session to use, as the value of the session_id cookie of www.odoo.sh. It is kept in memory only, and the keyring is not read. |
Every command that needs the session |
OSH_PROJECT |
The project, when --project is not given. |
Every command that takes --project |
OSH_BRANCH |
The branch, when --branch is not given. |
Every command that takes --branch |
OSH_DEBUG |
OSH_DEBUG=1 is --debug. |
Every command |
NO_COLOR |
Set to a value that is not empty, it leaves tables without colour and box drawing. | Every command that prints a table |
BROWSER |
The browsers to try for --open, in Python's webbrowser form, before the default one. |
osh builds open --open |
DISPLAY, WAYLAND_DISPLAY |
On Linux, with neither set, no browser is launched and the cookie is asked for. | osh auth login |
HTTPS_PROXY, ALL_PROXY, NO_PROXY |
The proxy that requests to Odoo.sh are sent through, and the hosts that are reached without it. The lowercase names are read too. HTTP_PROXY has no effect: every request is HTTPS. |
Every command that asks Odoo.sh |
SSL_CERT_FILE, SSL_CERT_DIR |
The certificate authorities trusted for those requests, as a file or a directory, in place of the system's. The file wins over the directory. | Every command that asks Odoo.sh |
- With
ODOUCHE_SESSIONset,osh auth loginstill stores the session it gets in the keyring, andosh auth logoutleaves the variable for you to unset. - Behind a proxy, the address
osh sshallows is the proxy's, which Odoo.sh sees.sshdoes not go through the proxy. - Git, which reads the checkout, and Rich, which draws the tables and the help, read variables of
their own, such as
GIT_DIRandTERM.
Shell completion¶
- It installs completion for the shell it is run from, such as bash, zsh or fish: a script under
the home directory, and for bash and zsh a line in
~/.bashrcor~/.zshrc. It takes effect in a new shell. osh --show-completionprints the script instead, to install it yourself.- Commands, options and the values an option lists are completed. Names of projects and branches are not: completing asks Odoo.sh nothing and does not open the keyring.
- It needs
oshon thePATH, so it does not go withuvx.