CLI Reference

Complete reference for the byteask command-line interface. The binary is named byteask; the underlying engine is byteask-engine.

Synopsis

byteask [OPTIONS] [PROMPT]
byteask <SUBCOMMAND> [OPTIONS]

Run byteask with no arguments to open the interactive TUI. Provide a PROMPT to seed the first message. Use a subcommand for specific operations.

Global flags

These flags are accepted by byteask (TUI mode) and most subcommands.

Config override

Flag	Description
`-c`, `--config key=value`	Override a single `config.toml` key (repeatable). Value is TOML-parsed. Dotted paths are supported, e.g. `-c tui.vim_mode_default=true`.

Shared options

Flag	Short	Type	Default	Description
`--image FILE`	`-i`	path (repeatable)	—	Attach an image to the initial prompt. Repeatable for multiple images.
`--model ID`	`-m`	string	from config	Model ID to use for this session. Overrides `config.toml`.
`--oss`	—	bool	`false`	Use a local open-source model provider.
`--local-provider NAME`	—	string	—	Local provider name: `"lmstudio"` or `"ollama"`. Requires `--oss`.
`--profile NAME`	`-p`	string	—	Load a named profile from `config.toml`.
`--sandbox MODE`	`-s`	enum	—	Set sandbox mode: `read-only`, `workspace-write`, or `danger-full-access`.
`--dangerously-bypass-approvals-and-sandbox`	—	bool	`false`	Skip all approval prompts and sandbox enforcement. Alias: `--yolo`.
`--dangerously-bypass-hook-trust`	—	bool	`false`	Run hooks without the hook trust check.
`--cd DIR`	`-C`	path	—	Change to this directory before running. Overrides cwd.
`--add-dir DIR`	—	path (repeatable)	—	Grant the agent write access to an additional directory (outside cwd).

Feature flags

Flag	Description
`--enable FEATURE`	Enable a named feature flag (repeatable).
`--disable FEATURE`	Disable a named feature flag (repeatable).

Remote / daemon

Flag	Description
`--remote ADDR`	Connect the TUI to a remote app-server (`ws://`, `wss://`, or `unix://` address).
`--remote-auth-token-env VAR`	Name of the environment variable holding the bearer token for the remote websocket.

TUI mode (default)

byteask [OPTIONS] [PROMPT]

Flag	Short	Default	Description
`PROMPT`	—	none	Initial prompt text. Opens TUI with this message pre-filled.
`--strict-config`	—	`false`	Exit with an error on any unknown field in `config.toml`.
`--ask-for-approval MODE`	`-a`	`on-request`	Approval policy: `untrusted`, `on-request`, or `never`.
`--search`	—	`false`	Enable live web search for this session.
`--no-alt-screen`	—	`false`	Render TUI inline instead of switching to the alternate screen buffer. Useful when you want scrollback.

Subcommands

`exec` (alias: `e`)

Non-interactive execution. Runs the agent against a prompt and exits.

byteask exec [OPTIONS] [PROMPT]
byteask exec [OPTIONS] -        # read prompt from stdin

Flag	Short	Default	Description
`PROMPT`	—	—	The task to execute. Pass `-` to read from stdin.
`--json` / `--experimental-json`	—	`false`	Print events as JSONL on stdout instead of human-readable output.
`-o FILE`, `--output-last-message FILE`	—	—	Write the agent's final message to a file.
`--color MODE`	—	`auto`	Color output mode: `always`, `never`, or `auto`.
`--ephemeral`	—	`false`	Do not write any session files to disk.
`--ignore-user-config`	—	`false`	Skip `~/.byteask/config.toml`.
`--ignore-rules`	—	`false`	Skip `.rules` files in the repository.
`--output-schema FILE`	—	—	JSON Schema file. The model's final response will conform to this schema.
`--skip-git-repo-check`	—	`false`	Allow running outside a Git repository.

All shared options also apply.

`review`

Review current code changes non-interactively.

byteask review [OPTIONS]

`login`

Manage authentication.

byteask login [OPTIONS]

Flag	Description
`--with-api-key`	Read an API key from stdin and store it.
`--with-access-token`	Read an access token from stdin.
`--device-auth`	Authenticate using device code flow.

`logout`

Remove stored credentials.

byteask logout

`resume`

Resume a saved session.

byteask resume           # interactive session picker
byteask resume <ID>      # resume a specific session

`fork`

Fork (branch off) a previous session.

byteask fork <SESSION_ID>

`archive`

Archive a session (hides it from the default session list).

byteask archive <SESSION_ID>

`unarchive`

Restore an archived session.

byteask unarchive <SESSION_ID>

`delete`

Permanently delete a session.

byteask delete <SESSION_ID>

`apply` (alias: `a`)

Apply the latest diff produced by ByteAsk via git apply.

byteask apply

`mcp`

Manage external MCP servers.

byteask mcp list
byteask mcp add <NAME> <COMMAND> [ARGS...]
byteask mcp remove <NAME>

`mcp-server`

Start ByteAsk as an MCP server (stdio transport). Allows Cursor, Claude Desktop, and other MCP clients to use ByteAsk as a tool.

byteask mcp-server

`plugin`

Manage plugins.

byteask plugin list
byteask plugin install <NAME>
byteask plugin remove <NAME>

`sandbox`

Run a shell command inside the ByteAsk sandbox without starting a full session.

byteask sandbox -- <COMMAND> [ARGS...]

`doctor`

Diagnose your installation, config, authentication, and network connectivity.

byteask doctor

`debug`

Low-level debugging sub-tools (model inspection, trace reduction, config dump).

byteask debug

`features`

Inspect all named feature flags and their current enabled/disabled state.

byteask features

`completion`

Generate shell tab-completion scripts.

byteask completion bash
byteask completion zsh
byteask completion fish
byteask completion powershell

`update`

Update ByteAsk to the latest version.

byteask --update        # can also be invoked as a flag on the main command

`app`

macOS and Windows only. Launch or bring to front the ByteAsk desktop application.

byteask app

`app-server` (experimental)

Run a background app server that TUI instances can connect to via --remote.

byteask app-server

`remote-control` (experimental)

Manage the ByteAsk daemon.

byteask remote-control

`exec-server` (experimental)

Run a standalone execution server that accepts tasks over the network.

byteask exec-server

`cloud` (alias: `cloud-tasks`) (experimental)

Browse and manage cloud task runs.

byteask cloud

Config file reference

~/.byteask/config.toml is read at startup. All keys are optional. Override any key on the command line with -c key=value.

Model

# Model ID string
model = "gpt-5.4"

# Reasoning effort applied to the model
# "none" | "minimal" | "low" | "medium" (default) | "high" | "xhigh" | "ultra"
model_reasoning_effort = "medium"

# Verbosity of model output
# "low" | "medium" (default) | "high"
model_verbosity = "medium"

# Absolute path to a JSON model catalog (overrides built-in catalog)
model_catalog_json = "/path/to/models-catalog.json"

# Context window size (tokens); 0 = use model default
model_context_window = 0

# Auto-compact when remaining context falls below this token count
model_auto_compact_token_limit = 0

Approval and sandbox

# "on-request" (default) | "untrusted" | "never"
approval_policy = "on-request"

# Who reviews auto-denials: "user" (default) | "auto_review"
approvals_reviewer = "user"

# Legacy integer field — use the --sandbox flag instead for string values
# sandbox_mode = 0

Web search

# "disabled" | "cached" (default) | "indexed" | "live"
web_search = "cached"

[tools.web_search]
context_size = "medium"            # "low" | "medium" | "high"
allowed_domains = []               # empty = all domains

TUI appearance

[tui]
vim_mode_default = false           # enable Vim keybindings by default
alternate_screen = "auto"          # "auto" | "always" | "never"
animations = true
session_picker_view = "dense"      # "comfortable" | "dense"
theme = "dracula"                  # syntax highlight theme name

Shell environment

[shell_environment_policy]
inherit = "all"                    # "all" | "core" | "none"
exclude = []                       # variable names to always strip
set = {}                           # variables to forcibly set
include_only = []                  # if non-empty, only these vars are passed

History

[history]
persistence = "save-all"           # "save-all" | "none"
max_bytes = 0                      # 0 = unlimited

MCP servers

[mcp_servers.my-server]
command = "/path/to/server"
args = ["--flag"]
env = { KEY = "value" }
enabled = true
required = false
startup_timeout_sec = 10
tool_timeout_sec = 30
enabled_tools = []      # whitelist specific tools (empty = all)
disabled_tools = []     # blacklist specific tools

For HTTP/SSE transport:

[mcp_servers.remote]
url = "https://example.com/mcp"
bearer_token_env_var = "MY_TOKEN"

Notifications

# Command to run when ByteAsk finishes a task (receives output as stdin)
notify = ["notify-send", "ByteAsk", "Task complete"]

Miscellaneous

# Communication style: "none" | "friendly" | "pragmatic"
personality = "none"

# Open files in: "vscode" | "vscode-insiders" | "windsurf" | "cursor" | "none"
file_opener = "vscode"

# Service tier: "default" | "priority" | "flex" | "fast"
service_tier = "default"

# Check for updates on startup
check_for_update_on_startup = true

Synopsis​

Global flags​

Config override​

Shared options​

Feature flags​

Remote / daemon​

TUI mode (default)​

Subcommands​

exec (alias: e)​

review​

login​

logout​

resume​

fork​

archive​

unarchive​

delete​

apply (alias: a)​

mcp​

mcp-server​

plugin​

sandbox​

doctor​

debug​

features​

completion​

update​

app​

app-server (experimental)​

remote-control (experimental)​

exec-server (experimental)​

cloud (alias: cloud-tasks) (experimental)​

Config file reference​

Model​

Approval and sandbox​

Web search​

TUI appearance​

Shell environment​

History​

MCP servers​

Notifications​

Miscellaneous​