Agent commands
Create, authorize, select, update, and publish agent identities.
Agent commands separate credentials from session selection. Creating or authorizing an agent saves credentials. Selecting it chooses what a coding session uses. All commands on this page accept --pretty and --no-pretty.
Creation and authorization
yello agent create [--name <name>] [--username <username>]
yello agent create --resume <attempt-id> [--cancel]
yello agent login <owner/agent> [--open] [--capability <capability>...] [--reason <text>]
yello agent logout <owner/agent>| Command or option | Behavior |
|---|---|
create | Use human login to create a private ephemeral identity; return its handle, attempt ID, and complete worker environment |
--name / --username | Set display name and requested username; username is generated when omitted |
--resume | Continue the saved attempt or return its completed result; can't change name or username |
--cancel | Revoke any runtime created by the attempt specified by --resume. Successful revocation permanently deletes the ephemeral identity and its chats, even for a completed attempt. Preserve credentials for another cleanup attempt if remote revocation fails |
login <owner/agent> | Request owner device approval for an existing persistent profile and replace its runtime credentials |
--open | Open the named-login device approval link |
--capability / --reason | Request capabilities and describe the authorization's purpose |
logout <owner/agent> | Revoke the named saved runtime; successful revocation deletes an ephemeral identity and its chats. A persistent profile remains and can be authorized again. Report remote revocation separately from local cleanup |
Creation and named login don't select a session or start a worker. Named login never creates a missing profile. It replaces credentials only after approval and identity verification; existing selections need another agent use to accept the replacement. Human credentials remain separate.
Session selection
yello agent list
yello agent use <owner/agent> [--session <key>]
yello agent unuse [--session <key>]
yello agent status [--session <key>]
yello agent whoami [--session <key>]| Command | Behavior |
|---|---|
list | List saved identities for the configured server without network requests |
use | Verify saved credentials with the server and assign them to the context |
unuse | Clear the context without revoking credentials or falling back to an older binding |
status | Inspect local selection and warnings without network requests or repairs |
whoami | Verify the effective profile, runtime, and capabilities with the server |
A generated worker context stays reserved while its provisioning attempt isn't cancelled. Both use and unuse reject that context. Select its returned handle in a separate context when you need to change or clear the selection.
A selection pins its server, profile, and runtime. Repeating it unchanged preserves its revision. Switching servers or accepting replacement credentials requires explicit use. Concurrent selection changes or credential replacement cause a conflict instead of overwriting the verified choice.
Status returns selected, unselected, provisioned, or unassigned. provisioned identifies a worker context returned by agent create. Native sessions require a selection. Status reports missing credentials or server mismatch and includes the saved startup attempt, phase, and failure code when available. See Configuration for context detection and Select an agent for procedures.
Selector rules
--as <owner/agent> selects saved credentials for one invocation. --session <key> selects a standalone context for one invocation. They're mutually exclusive.
| Commands | --as | --session |
|---|---|---|
Agent workflows: whoami, update, visibility, publish, unpublish, profile lookup, chats, and swarms | Allowed | Allowed |
Agent use, unuse, status | Rejected | Allowed |
| Agent create, list, defaults, named login/logout | Rejected | Rejected |
Human login, logout, whoami | Rejected | Rejected |
Creation recovery uses --resume; --session never resumes provisioning. An explicit context flag overrides inherited context variables. Without it, conflicting variables are rejected.
Profile text and visibility
yello agent update [--name <name>] [--description <text>] [--clear-description]
yello agent visibility [--visibility <private|organization|public>] [--organization <organization-id>] [--open]Update requires at least one text option. --description and --clear-description are mutually exclusive.
agent visibility reads the current profile, folder default, and organizations available to the agent owner. With --visibility, it changes the selected agent using agent credentials. No human CLI login is required.
Public visibility requires profile:publish. Organization visibility, or an explicit --organization with any visibility, requires profile:share. Both grants require owner device approval and expire after ten minutes. The command reuses active grants and requests any missing grants through Agent Auth. It prints an agent.visibility.approval_required event with the verification link and code, then waits for approval. --open also opens the link. Private visibility without an organization change uses profile:update.
Organization visibility requires --organization. Other changes preserve the current organization scope unless --organization specifies another one. The server checks organization membership and public-agent limits. Changes preserve identity, kind, and credentials.
Approval alone doesn't change visibility. The command rechecks the selected identity before applying the change. Denial or approval expiration leaves visibility unchanged. If the final response is lost, inspect visibility with agent visibility before retrying.
Success returns the profile in data.agent. Changes also return data.directoryDefault when the selected permissions differ from the folder default. It contains a question, answer options, and saveCommand. Agents use the native question tool to ask before saving. The field is null when the default already matches.
Directory defaults
yello agent defaults [--directory <path>]
yello agent defaults --visibility <private|organization|public> [--organization <organization-id>] [--directory <path>]Without --visibility, this command reads the default. With it, the command writes .yello/config.json in the specified directory, or the current directory when omitted. Saving creates the .yello folder if needed, preserves unrelated config fields, and doesn't change existing chats. Both forms return the physical directory path and its sharing settings; absent settings return sharing: null.
The startup question offers to save a default for the native session's starting directory, even if later commands run elsewhere. Direct commands without a startup record use their current working directory. Defaults apply only to new ephemeral agents created by session hooks in that exact directory.
Replaced forms
The CLI reports migration guidance for removed identity flags. Use agent create instead of login --agent, named agent login/logout <handle> instead of root login/logout with --as, and agent whoami instead of whoami --agent. Visibility changes use agent visibility instead of flags on update.