--- title: "subako agent" description: "Agents: the unit of work a session runs, and its published versions" --- [CLI reference](/cli) ## `subako agent` Agents: the unit of work a session runs, and its published versions ### Usage ```text Usage: subako agent ``` ### Subcommands - [`subako agent create`](#subako-agent-create) - [`subako agent list`](#subako-agent-list) - [`subako agent show`](#subako-agent-show) - [`subako agent publish`](#subako-agent-publish) - [`subako agent config-example`](#subako-agent-config-example) - [`subako agent versions`](#subako-agent-versions) - [`subako agent rename`](#subako-agent-rename) - [`subako agent security`](#subako-agent-security) - [`subako agent set-security`](#subako-agent-set-security) - [`subako agent delete`](#subako-agent-delete) ### Options #### `--help` Print help - Short option: `-h`. ## `subako agent create` Create an agent in the selected workspace. An agent holds no configuration of its own; its versions do ### Usage ```text Usage: subako agent create [OPTIONS] --name ``` ### Options #### `--name ` - Required. #### `--profile ` Credential profile to act as. Defaults to the current one #### `--credentials-file ` Path to the credentials file. Defaults to SUBAKO_CREDENTIALS_FILE, then ~/.config/subako/credentials.json. #### `--help` Print help - Short option: `-h`. ## `subako agent list` List the selected workspace's agents ### Usage ```text Usage: subako agent list [OPTIONS] ``` ### Options #### `--profile ` Credential profile to act as. Defaults to the current one #### `--credentials-file ` Path to the credentials file. Defaults to SUBAKO_CREDENTIALS_FILE, then ~/.config/subako/credentials.json. #### `--help` Print help - Short option: `-h`. ## `subako agent show` Read one agent's row ### Usage ```text Usage: subako agent show [OPTIONS] ``` ### Arguments #### `` - Required. ### Options #### `--profile ` Credential profile to act as. Defaults to the current one #### `--credentials-file ` Path to the credentials file. Defaults to SUBAKO_CREDENTIALS_FILE, then ~/.config/subako/credentials.json. #### `--help` Print help - Short option: `-h`. ## `subako agent publish` Publish a configuration as the agent's next version ### Usage ```text Usage: subako agent publish [OPTIONS] --config --model-provider ``` ### Arguments #### `` - Required. ### Options #### `--config ` JSON file holding the version's configuration. Its shape is the server's: it names the model, and may grant mcp servers and skills. The provider is named by --model-provider, not in here - Required. #### `--model-provider ` Provider the version runs against, as `model-provider list` shows it. Its format must match the one the config's model speaks - Required. #### `--profile ` Credential profile to act as. Defaults to the current one #### `--credentials-file ` Path to the credentials file. Defaults to SUBAKO_CREDENTIALS_FILE, then ~/.config/subako/credentials.json. #### `--help` Print help - Short option: `-h`. ## `subako agent config-example` Print a configuration that publishes as it stands, to redirect into a file and edit. Needs no server ### Usage ```text Usage: subako agent config-example --format ``` ### Options #### `--format ` Which format the example's model speaks. It must match the format of the provider the version is published against - Required. - Possible values: - `anthropic` - `openai_responses` #### `--help` Print help - Short option: `-h`. ## `subako agent versions` List an agent's versions, marking the one a new session would bind ### Usage ```text Usage: subako agent versions [OPTIONS] ``` ### Arguments #### `` - Required. ### Options #### `--profile ` Credential profile to act as. Defaults to the current one #### `--credentials-file ` Path to the credentials file. Defaults to SUBAKO_CREDENTIALS_FILE, then ~/.config/subako/credentials.json. #### `--help` Print help - Short option: `-h`. ## `subako agent rename` Rename an agent, leaving its versions alone ### Usage ```text Usage: subako agent rename [OPTIONS] --name ``` ### Arguments #### `` - Required. ### Options #### `--name ` New name for the agent - Required. #### `--profile ` Credential profile to act as. Defaults to the current one #### `--credentials-file ` Path to the credentials file. Defaults to SUBAKO_CREDENTIALS_FILE, then ~/.config/subako/credentials.json. #### `--help` Print help - Short option: `-h`. ## `subako agent security` Read an agent's security document: how its sessions answer a browser ### Usage ```text Usage: subako agent security [OPTIONS] ``` ### Arguments #### `` - Required. ### Options #### `--profile ` Credential profile to act as. Defaults to the current one #### `--credentials-file ` Path to the credentials file. Defaults to SUBAKO_CREDENTIALS_FILE, then ~/.config/subako/credentials.json. #### `--help` Print help - Short option: `-h`. ## `subako agent set-security` Replace an agent's security document. Every field is stated in full, so a flag left out resets that field: with no flags at all the agent returns to refusing every browser ### Usage ```text Usage: subako agent set-security [OPTIONS] ``` ### Arguments #### `` - Required. ### Options #### `--allowed-origin ` Browser origin whose pages may call the agent's sessions, repeated for each one: a scheme, a host, and an optional port, exactly as a browser sends `Origin` (`https://app.example.com`, no path and no trailing slash) - May be repeated to supply multiple values. #### `--profile ` Credential profile to act as. Defaults to the current one #### `--credentials-file ` Path to the credentials file. Defaults to SUBAKO_CREDENTIALS_FILE, then ~/.config/subako/credentials.json. #### `--help` Print help - Short option: `-h`. ## `subako agent delete` Permanently delete an agent, its versions, and every session that ran them. Billing history is retained; the transcripts are not ### Usage ```text Usage: subako agent delete [OPTIONS] ``` ### Arguments #### `` - Required. ### Options #### `--yes` Skip the typed confirmation. For scripts that have already asked - Default: `false`. #### `--profile ` Credential profile to act as. Defaults to the current one #### `--credentials-file ` Path to the credentials file. Defaults to SUBAKO_CREDENTIALS_FILE, then ~/.config/subako/credentials.json. #### `--help` Print help - Short option: `-h`.