# obss project ai and setup - Obss

CLI
obss project ai and setup
Inspect and change agents, custom agents, models, and Obss AI features, check MCP server sign-ins and tools, and get secure setup links.
These commands set up the agents and models a project runs, and find what still needs a value in the dashboard.
Commands
What they cover
obss project ai
Agents
,
custom agents
,
model providers
and their models, and the model of each
Obss AI feature
obss mcp accounts
,
obss setup links
What still needs a sign-in or a secret value
obss mcp tools
The tools of an MCP server
Secret values never pass through the CLI. API keys, OAuth sign-ins, secret headers, and environment variable values go in the dashboard, and the CLI returns the exact link.
obss project ai inspect
Read agents, custom agents, provider connections, models, and the model of each Obss AI feature. It never starts a model refresh or changes settings.
obss
project
ai
inspect
[flags]
Plugin (MCP) tool:
inspect_project_ai
Flags
Flag
Type
Default
Description
--view
roles
,
providers
,
agents
,
models
,
agent_registry
roles
What to read. See
Result fields
.
--provider-connection-id
string
models
view: the
aic_…
connection whose models to list.
--agent-key
string
models
view: the
acp-…
custom agent whose models to list.
--access
shared
,
private
providers
view: the organization’s API keys, or your own accounts.
--connection-state
connected
,
needs_attention
,
not_connected
providers
view:
needs_attention
is saved but must be fixed.
--query
string
agent_registry
view: match the registry ID, name, or description.
--limit
integer
100
Results per page, up to 500 (default 100).
--cursor
string
The
nextCursor
from the previous page.
Also takes the
global flags
.
Examples
List provider connections that you must fix:
obss
project
ai
inspect
--view
providers
--connection-state
needs_attention
List agents, with each custom agent’s status and fix:
obss
project
ai
inspect
--view
agents
List a custom agent’s models:
obss
project
ai
inspect
--view
models
--agent-key
acp-0123456789abcdef
Find an agent in the ACP Registry:
obss
project
ai
inspect
--view
agent_registry
--query
gemini
Result fields
View
What it lists
roles
Each Obss AI feature (
ask
Ask Obss,
judge
Evals,
sweep
Insights,
consolidation
Experiment insights), its saved model, and
availability
, with
availabilityReason
and
availabilityMessage
when it can’t run
providers
Each provider connection with its
access
(
shared
or
private
),
connectionState
, and model refresh state (
modelRefresh
)
agents
Every agent and its kind (
built_in
or
custom
), with a
custom
block
for custom agents
models
The models of one connection or custom agent (
--provider-connection-id
or
--agent-key
)
agent_registry
The ACP Registry agents that you can create a custom agent from
blockers
is empty when you can run models. Otherwise it says why not, such as no working provider, with the
setupUrl
that fixes it.
modelRefresh
has
status
(
queued
,
running
,
succeeded
, or
failed
),
listedAt
, and the counts of the last refresh.
listedAt
is the time the refresh read the provider’s list, and
null
before that. While
status
is
running
and
listedAt
is set, the
models
view has the listed models, and the
checks
that decide which ones you can select still run. The text output then says
Models listed; checking which ones you can use
.
Each model has
contextWindowTokens
,
contextWindowSource
(
catalog
or
stated
), and your
statedContextWindowTokens
.
suggestedContextWindow
(
tokens
,
catalog
,
catalogModelId
) comes from a public catalog and applies only once you state it with
set_model_context_windows
.
A custom agent’s model has
agentState
:
current
,
stale
(
Not confirmed
), or
unavailable
(
Unavailable
).
Custom agent fields
Custom agents are in private beta. Email
support@obss.app
to enable them for your organization.
In the
agents
view, each custom agent has a
custom
block:
Field
Meaning
status
needs_values
,
testing
,
needs_attention
,
not_tested
, or
ready
. The dashboard shows
Needs values
,
Testing
,
Needs attention
,
Not tested
, and
Ready
.
description
The agent’s description in Obss, or empty
revision
Send it as
expectedRevision
to change or remove the agent.
connectionId
The agent’s own
aic_
connection. Its models are the
models
view of this ID, and
set_model_enabled
takes it.
url
The agent’s page in the dashboard
definition
How the agent installs, its arguments, and its skills folder
env
Each environment variable name, whether it has a value, and the dashboard link where you set it
envNote
What to know about
env
, when there is something to know
testBlockers
Why
test-agent
can’t start in this project yet. Empty when it can.
handshake
The start-up details of
latestRun
, such as
failure.message
,
failure.detail
, and
authMethods
fix
For
needs_attention
, the failed step and what to change
mcpServersRefused
true
when a run at the current revision refused its MCP servers. Preflight then blocks treatments with MCP servers for this agent.
latestRun
The newest finished run at the current revision that wasn’t cancelled and didn’t refuse its MCP servers: its
runId
,
experimentId
,
status
, and
url
obss project ai apply
Create or change custom agents, turn agents and models on or off, state context windows, refresh model lists, and set each Obss AI feature’s model and instructions.
obss
project
ai
apply
--operation
<
jso
n
>
[flags]
Plugin (MCP) tool:
manage_project_ai
Flags
Flag
Type
Default
Description
--operation
string
The operation as one JSON object.
--operation-file
file path
A file that holds the operation JSON.
Pass one of the two.
obss schema project ai apply
prints the full schema. Also takes the
global flags
.
Apply operations
action
What it does
Main fields
set_agents
Turn agents on or off in the project
expectedRevision
, and
agents
(
[{"key","enabled"}]
) or
enabled
for every agent
set_model_enabled
Turn one model on or off
connectionId
(
aic_…
),
modelId
(
aim_…
),
enabled
set_models_enabled
Turn a connection’s models on or off
connectionId
,
enabled
, and
modelIds
for a subset (at most 5,000)
set_model_context_windows
State models’ context windows on an organization connection
connectionId
,
models
(
[{"modelId","contextWindowTokens"}]
, at most 5,000).
null
clears one.
refresh_models
Refresh model lists in the background
connectionIds
(at most 200), or omit for every connection you can refresh
set_roles
Set each Obss AI feature’s model, effort, and custom instructions
expectedOrganizationRevision
,
roleBindings
create_custom_agent
Create a custom agent
name
(at most 120 characters),
source
, and optional
description
,
env
, and
skillsFolder
update_custom_agent
Change a custom agent. Omitted fields keep their value.
agentKey
,
expectedRevision
, and the fields to change
A custom agent’s
source
is
registry
(an ACP Registry agent, such as
{"kind":"registry","registryId":"gemini"}
),
manual
(an npm package, Python package, or download with its SHA-256, plus
args
), or
agent_json
(a standard
agent.json
).
env
lists variable names only; the result gives the
acp-…
key, the agent’s page, and the dashboard link for each value.
Examples
Turn on every agent in the project:
obss
project
ai
apply
--operation
'{"action":"set_agents","expectedRevision":1,"enabled":true}'
--output
json
Create a custom agent from the ACP Registry:
obss
project
ai
apply
--operation
'{"action":"create_custom_agent","name":"Gemini CLI","source":{"kind":"registry","registryId":"gemini"},"env":["GEMINI_API_KEY"]}'
--output
json
Create a custom agent from an npm package with an exact version:
obss
project
ai
apply
--operation
'{"action":"create_custom_agent","name":"My agent","source":{"kind":"manual","install":{"kind":"npm","package":"my-agent@1.4.2"},"args":"acp --verbose"},"env":["MY_AGENT_API_KEY"]}'
--output
json
State a model’s context window:
obss
project
ai
apply
--operation
'{"action":"set_model_context_windows","connectionId":"aic_4f0e2c9b","models":[{"modelId":"aim_7a13d5e0","contextWindowTokens":500000}]}'
Refresh model lists, then check progress:
obss
project
ai
apply
--operation
'{"action":"refresh_models"}'
--output
json
obss
project
ai
inspect
--view
providers
Notes
The provider’s current context window wins over a stated one.
After
refresh_models
, resolve any failed list’s
actionRequired
, then poll
obss project ai inspect
until
counts.modelRefresh.refreshing
is 0. To read a provider’s models before its checks finish, read the
models
view once that provider’s
modelRefresh.listedAt
is set.
A refused operation changes nothing and exits
4
with one of these codes:
Code
When
validation_error
The operation isn’t valid.
configuration_changed
A revision is stale (
set_agents
or a custom agent).
details.currentRevision
has the current one.
obss project ai test-agent
Start a Test agent run, which checks that a custom agent installs, starts, and answers.
obss
project
ai
test-agent
<
agent-ke
y
>
[flags]
Plugin (MCP) tool:
test_custom_agent
Uses 1 run from your balance. In Ask Obss, you approve each call.
Arguments
Argument
Description
<agent-key>
Required. The custom agent’s key (
acp-…
).
Flags
Flag
Type
Default
Description
--attempt-id
string
A new ID
An ID you choose, so that a retry doesn’t repeat the change.
Also takes the
global flags
.
Examples
Test an agent, watch the run, then read its status:
obss
project
ai
test-agent
acp-0123456789abcdef
obss
experiments
watch
<
launch-i
d
>
obss
project
ai
inspect
--view
agents
Notes
The run is one short
Agent check
task with
Agent default
, the
Raw Agent
treatment (no tools), no project files, and Evals and Insights off. Watch the launch ID with
obss experiments watch
. Each finished run with these settings updates the agent’s status.
The command refuses while
custom.testBlockers
names a blocker, with the first one’s code:
Code
Fix
custom_agent_test_running
A Test agent run with these settings is in progress. Open it.
custom_agent_disabled
Turn the agent on with
set_agents
in
obss project ai apply
.
custom_agent_value_missing
Set each value in the dashboard with its link.
custom_agent_default_model_disabled
Turn on
Agent default
with
set_model_enabled
and the blocker’s
connectionId
and
modelId
.
obss project ai delete
Remove a custom agent, delete or reset an organization provider connection, or disconnect your own account from a provider.
obss
project
ai
delete
--operation
<
jso
n
>
[flags]
Plugin (MCP) tool:
delete_project_ai
Removing a custom agent clears its environment variable values. Deleting or resetting a provider connection affects every project in the organization. In a terminal, the CLI asks you to confirm; with
--output json
or no terminal, pass
--yes
.
Flags
Flag
Type
Default
Description
--operation
string
The operation as one JSON object.
--operation-file
file path
A file that holds the operation JSON.
--yes
boolean
false
Confirm without a prompt. Required with
--output json
or without a terminal.
Also takes the
global flags
.
Delete operations
action
What it does
Fields
remove_custom_agent
Remove a custom agent
agentKey
,
expectedRevision
delete_connection
Delete a custom organization provider connection
connectionId
,
expectedOrganizationRevision
,
expectedSecretRevision
,
expectedEditRevision
reset_connection
Reset a built-in organization provider connection
connectionId
,
expectedOrganizationRevision
,
expectedSecretRevision
,
expectedEditRevision
disconnect_personal_connection
Disconnect your own account from a personal provider, such as a subscription on
Profile → Integrations
connectionId
Examples
Remove a custom agent:
obss
project
ai
delete
--operation
'{"action":"remove_custom_agent","agentKey":"acp-0123456789abcdef","expectedRevision":2}'
--yes
--output
json
Notes
A removed custom agent no longer shows in new experiments or the Agents list, and its past results keep its name. Obss refuses the removal while a run of the agent is in progress, either a Test agent run or an experiment. Removing it again returns the same result.
A personal disconnect changes only your own account in this organization.
Pass the revisions from
obss project ai inspect
. A refused removal changes nothing and exits
4
with one of these codes:
Code
When
configuration_changed
A stale revision on
remove_custom_agent
.
details.currentRevision
has the current one.
project_ai_configuration_changed
A stale revision on the other actions
project_ai_target_not_found
The agent or connection is already gone.
obss mcp accounts inspect
Check whether an MCP server has the sign-in and headers it needs, without showing any secret.
obss
mcp
accounts
inspect
<
mcp-i
d
>
[flags]
Plugin (MCP) tool:
inspect_mcp_account
Arguments
Argument
Description
<mcp-id>
Required. The MCP server’s current
mcp_
ID.
Takes only the
global flags
.
Examples
Check an MCP server’s connection:
obss
mcp
accounts
inspect
mcp_2e8b6f13
Result fields
Field
Meaning
ready
Whether the server can run. When saved values aren’t
bound to the current address
, it’s
false
.
recovery
When the server can’t run: a
message
, the
action
to take,
setupUrl
,
retryAt
(when to try again), and
apiKeyAlternative
when the server has an API key option
setupUrl
Where a person signs in or adds a header. For unbound saved values, it’s the version’s
Tools
tab, where a person selects
Refresh
.
redirectUri
For
Sign in with provider
, the
address to add to your OAuth app
oauthAppConfigured
Whether a Client ID is saved
obss mcp accounts detect-auth
Detect how an MCP server authenticates, and whether that matches its saved configuration.
obss
mcp
accounts
detect-auth
<
mcp-i
d
>
[flags]
Plugin (MCP) tool:
detect_mcp_auth_mode
Arguments
Argument
Description
<mcp-id>
Required. The MCP server’s current
mcp_
ID.
Takes only the
global flags
.
Examples
Detect an MCP server’s sign-in method:
obss
mcp
accounts
detect-auth
mcp_2e8b6f13
--output
json
Result fields
Field
Meaning
detectedAuthMode
oauth
,
headers
,
unreachable
, or
not_applicable
configurationMatches
false
when the detected mode differs from the saved one. Then review the server at
setupUrl
.
registration
For
oauth
:
automatic
(the provider registers Obss by itself),
oauth_app_required
(you create an OAuth app and paste its Client ID and Client secret at
setupUrl
, which opens the
OAuth app
section), or
unknown
.
null
for other modes.
redirectUri
For
oauth
, the address to add to the OAuth app.
null
for other modes.
oauthAppConfigured
Whether the server has a saved Client ID
setupUrl
The dashboard page for the server
See
MCP server sign-in
.
obss mcp tools list
List the tools that an MCP server listed when Obss last checked it.
obss
mcp
tools
list
<
mcp-i
d
>
[flags]
Plugin (MCP) tool:
list_mcp_server_tools
Arguments
Argument
Description
<mcp-id>
Required. The MCP server’s current
mcp_
ID.
Flags
Flag
Type
Default
Description
--version-id
string
Latest version
An
mcpver_
version of the server.
--query
string
Only tools whose name, title, or description contains this text.
--after-position
integer
The
nextAfterPosition
from the previous page.
--limit
integer
50
Results per page, up to 200 (default 50).
--full
boolean
false
Add each tool’s input schema.
Also takes the
global flags
.
Examples
Find the tools about issues:
obss
mcp
tools
list
mcp_2e8b6f13
--query
issue
--output
json
Result fields
Field
Meaning
canTurnOff
Whether a treatment can
turn the tool off
lastChange
Tools the last change added, removed, or changed: up to 20 names per list, with full counts
usageRunCount
The project’s runs whose treatment included this version
onRunCount
,
runCount
,
callCount
Per tool: runs with the tool on, runs that called it, and its calls. See
See how runs use each tool
.
offInTreatmentCount
,
offInTreatmentIds
Treatments that turn the tool off on any version, and up to 20 of their IDs
headerValuesBound
false
when saved values (header values, an OAuth app’s client secret) aren’t
bound to the address
. Only a person’s
Refresh
at
setupUrl
binds them; until then
obss mcp tools refresh
fails with
mcp_tool_check_needs_web
and launches stop with
mcp_header_values_unbound
.
truncated
,
nextAfterPosition
Whether more tools remain, and the position to pass to
--after-position
Notes
Tool titles, descriptions, and hints are the server’s own text.
obss mcp tools refresh
Check an MCP server’s tools now and list them.
obss
mcp
tools
refresh
<
mcp-i
d
>
[flags]
Plugin (MCP) tool:
refresh_mcp_server_tools
Arguments
Argument
Description
<mcp-id>
Required. The MCP server’s current
mcp_
ID.
Flags
Flag
Type
Default
Description
--wait-ms
integer
Wait up to this many milliseconds, at most 25,000, for the check to finish.
Also takes
--version-id
,
--query
,
--after-position
,
--limit
, and
--full
, as in
obss mcp tools list
, and the
global flags
.
Examples
Check the server and wait for the result:
obss
mcp
tools
refresh
mcp_2e8b6f13
--wait-ms
20000
--output
json
Result fields
The fields of
obss mcp tools list
(
canTurnOff
,
lastChange
,
usageRunCount
,
onRunCount
,
runCount
,
callCount
,
offInTreatmentCount
,
offInTreatmentIds
,
headerValuesBound
,
truncated
, and
nextAfterPosition
), plus
refresh
, which is
running
until the check finishes.
Notes
A check that is already running is joined, not started again. If the wait ends first,
refresh
stays
running
, and you read the list again with
obss mcp tools list
.
A server that needs your account connection or a header value returns that status and its
setupUrl
.
The command never sends saved header values to an address they aren’t bound to, and it never binds them. When
headerValuesBound
is
false
, it fails with
mcp_tool_check_needs_web
and exits
4
. Open
error.details.setupUrl
, check the address under
Refresh
, and select
Refresh
. Then run
obss mcp tools list
.
obss setup links
Get the dashboard link for every secure input: account connections, API keys, secret headers, and other secret values.
obss
setup
links
[flags]
Plugin (MCP) tool:
get_setup_links
Takes only the
global flags
.
Examples
Get the setup links as JSON:
obss
setup
links
--output
json
Result fields
issues
lists each machine, MCP server, CLI, and SDK that still needs a required value or your account connection, with the
setupUrl
where a person does that step. An MCP server whose saved values aren’t bound to its address has a field of scope
address
, with its
Tools
tab as
setupUrl
. The list is empty when nothing is missing.
Next steps
Custom agents
Sources, values, status, and models of a custom agent.
Model providers
Connect providers and state context windows in the dashboard.
obss experiments
Launch the agents and models you turned on.
Obss AI features
Choose the model of each Obss AI feature.
data
quota and notifications
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform