# obss login, whoami, and upgrade - Obss

CLI
obss login, whoami, and upgrade
Sign the obss CLI in and out, check who it acts as, show its version, update it, and print each command’s JSON Schema.
These commands work on the CLI itself rather than on a project. All of them except
obss whoami
run without a sign-in, and only
whoami
has a Plugin (MCP) tool. API keys and background updates are on the
CLI reference
.
obss login
Sign in to Obss with your browser.
obss
login
[flags]
No Plugin (MCP) tool: an MCP host
signs in with OAuth
when it first calls a tool.
Flags
Flag
Type
Default
Description
--no-browser
boolean
false
Print the sign-in link without opening a browser, for a remote machine.
Also takes the
global flags
.
Examples
Sign in on this computer, or from a remote machine by opening the printed link on any computer:
obss
login
obss
login
--no-browser
Notes
The CLI prints the sign-in link and a confirmation code on stderr, even with
--quiet
, and in a terminal it also opens the link in your browser. When you confirm the code in the browser, the command finishes, saves your sign-in, and makes your organization the active one. The result names you, your organization, and the dashboard URL.
While
OBSS_API_KEY
is set,
obss login
refuses to sign in and exits with code
2
. Unset the variable first, as
Use an API key
explains.
obss whoami
Show who the CLI acts as, in which organization, and whether it uses a sign-in or an API key.
obss
whoami
[flags]
Plugin (MCP) tool:
get_identity
Takes only the
global flags
.
Examples
obss
whoami
--output
json
Result fields
Field
Description
user
The person the CLI acts as.
organization
The organization, with its
id
.
dashboardUrl
The dashboard address.
credential
sign_in
for a browser sign-in, or
api_key
when
OBSS_API_KEY
is set.
Notes
To keep a script in one organization, pass
organization.id
to
--expected-organization-id
on later commands: they then fail if your sign-in moves to another organization. When you’re not signed in, the command exits with code
3
and tells you to run
obss login
.
obss logout
Remove your saved sign-in and your saved project from this computer.
obss
logout
[flags]
No Plugin (MCP) tool: it acts only on the CLI on this computer.
Takes only the
global flags
.
Examples
obss
logout
Notes
Running it twice is safe. While
OBSS_API_KEY
is set, commands keep using the key after you log out, and the CLI says so on stderr.
obss version
Show the installed version, its release channel, the platform, and whether background updates are on.
obss
version
[flags]
No Plugin (MCP) tool: it acts only on the CLI on this computer.
Takes only the
global flags
.
Examples
obss
version
--output
json
Result fields
Field
Description
version
,
channel
The installed version and its release channel.
platform
The platform, such as
darwin-arm64
.
autoUpdate
on
, or
off
in the cases that
Background updates
lists.
Notes
obss --version
prints the version and channel on one line. Neither command contacts Obss.
obss upgrade
Replace the installed
obss
binary with the latest release for its channel.
obss
upgrade
[flags]
No Plugin (MCP) tool: it acts only on the CLI on this computer.
Flags
Flag
Type
Default
Description
--check
boolean
false
Report the latest version and install nothing.
--force
boolean
false
Install the latest release even when you already have it.
Also takes the
global flags
.
Examples
See whether a newer release exists, then install it:
obss
upgrade
--check
obss
upgrade
Result fields
Field
Description
currentVersion
,
latestVersion
The installed release and the latest one.
path
Where the binary is.
action
What the command did, from the next table.
action
Meaning
upgraded
The CLI installed the latest release.
already-current
You already have it. Nothing changed.
check
With
--check
: a newer release exists. Nothing changed.
unsupported
The CLI runs from source, so there’s no binary to replace. Reinstall with the
install script
.
Notes
The command doesn’t contact the Obss API, so it still runs when other commands fail with
client_update_required
. Use it when you don’t want to wait for a
background update
.
If the CLI can’t write its binary, the command tells you to reinstall in a folder you can write, such as
~/.local/bin
or
~/.obss/bin
. You don’t need
sudo
.
obss schema
Print machine-readable command definitions as JSON Schema.
obss
schema
[command]
No Plugin (MCP) tool: an MCP host reads each tool’s input schema from the server.
Arguments
Argument
Description
[command]
The command to describe, such as
experiments launch
. Without it, every command is listed with its summary.
Takes only the
global flags
.
Examples
List every command, then read the launch plan schema before you write a plan:
obss
schema
obss
schema
experiments
launch
--output
json
Result fields
For one command, the result has these fields:
Field
Description
name
,
summary
,
description
The command and what it does.
requiresAuth
Whether it needs a sign-in or an API key.
args
Each argument, and whether it’s optional or takes several values.
flags
The flags as JSON Schema, with types, defaults, and limits.
payload
The JSON input it reads from a flag or file, such as the
plan
of
experiments launch
, the
operation
of
resources apply
, or the
query
of
data query
.
null
when there is none.
output
The JSON Schema of
data
in the
JSON envelope
.
examples
Example invocations.
Notes
An unknown command name fails with
usage_error
. The command doesn’t contact Obss.
Next steps
obss projects
List projects and choose the one later commands use.
CLI reference
Global flags, output, exit codes, and conventions.
Profile and API keys
Create a personal API key for CI jobs and other places where nobody can sign in.
Overview
projects
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform