CLI

AlphaBase CLI options and commands.

The AlphaBase CLI by default starts the TUI when run without any arguments.

alphabase

But it also accepts commands as documented on this page. This allows you to interact with AlphaBase programmatically.

alphabase run "Explain how closures work in JavaScript"

tui

Start the AlphaBase terminal user interface.

alphabase [project]

Flags

Flag	Short	Description
`--continue`	`-c`	Continue the last session
`--session`	`-s`	Session ID to continue
`--fork`		Fork the session when continuing (use with `--continue` or `--session`)
`--prompt`		Prompt to use
`--model`	`-m`	Model to use in the form of provider/model
`--agent`		Agent to use
`--port`		Port to listen on
`--hostname`		Hostname to listen on

Commands

The AlphaBase CLI also has the following commands.

agent

Manage agents for AlphaBase.

alphabase agent [command]

attach

Attach a terminal to an already running AlphaBase backend server started via serve or web commands.

alphabase attach [url]

This allows using the TUI with a remote AlphaBase backend. For example:

# Start the backend server for web/mobile access
alphabase web --port 4096 --hostname 0.0.0.0

# In another terminal, attach the TUI to the running backend
alphabase attach http://10.20.30.40:4096

Flags

Flag	Short	Description
`--dir`		Working directory to start TUI in
`--session`	`-s`	Session ID to continue

create

Create a new agent with custom configuration.

alphabase agent create

This command will guide you through creating a new agent with a custom system prompt and tool configuration.

list

List all available agents.

alphabase agent list

auth

Command to manage credentials and login for providers.

alphabase auth [command]

AlphaBase is powered by the provider list at Models.dev, so you can use alphabase auth login to configure API keys for any provider you’d like to use. This is stored in ~/.local/share/alphabase/auth.json.

alphabase auth login

When AlphaBase starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a .env file in your project.

list

Lists all the authenticated providers as stored in the credentials file.

alphabase auth list

Or the short version.

alphabase auth ls

logout

Logs you out of a provider by clearing it from the credentials file.

alphabase auth logout

debug

Debugging and troubleshooting tools.

alphabase debug [command]

Includes subcommands for inspecting config, files, LSP status, snapshots, and harness diagnostics.

github

Manage the GitHub agent for repository automation.

alphabase github [command]

install

Install the GitHub agent in your repository.

alphabase github install

This sets up the necessary GitHub Actions workflow and guides you through the configuration process. Learn more.

run

Run the GitHub agent. This is typically used in GitHub Actions.

alphabase github run

Flags

Flag	Description
`--event`	GitHub mock event to run the agent for
`--token`	GitHub personal access token

mcp

Manage Model Context Protocol servers.

alphabase mcp [command]

add

Add an MCP server to your configuration.

alphabase mcp add

This command will guide you through adding either a local or remote MCP server.

list

List all configured MCP servers and their connection status.

alphabase mcp list

Or use the short version.

alphabase mcp ls

auth

Authenticate with an OAuth-enabled MCP server.

alphabase mcp auth [name]

If you don’t provide a server name, you’ll be prompted to select from available OAuth-capable servers.

You can also list OAuth-capable servers and their authentication status.

alphabase mcp auth list

Or use the short version.

alphabase mcp auth ls

logout

Remove OAuth credentials for an MCP server.

alphabase mcp logout [name]

debug

Debug OAuth connection issues for an MCP server.

alphabase mcp debug <name>

generate

Generate the OpenAPI specification JSON for the local alphabase server.

alphabase generate

models

List all available models from configured providers.

alphabase models [provider]

This command displays all models available across your configured providers in the format provider/model.

This is useful for figuring out the exact model name to use in your config.

You can optionally pass a provider ID to filter models by that provider.

alphabase models anthropic

Flags

Flag	Description
`--refresh`	Refresh the models cache from models.dev
`--verbose`	Use more verbose model output (includes metadata like costs)

Use the --refresh flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in AlphaBase.

alphabase models --refresh

run

Run alphabase in non-interactive mode by passing a prompt directly.

alphabase run [message..]

This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.

alphabase run Explain the use of context in Go

You can also attach to a running alphabase serve instance to avoid MCP server cold boot times on every run:

# Start a headless server in one terminal
alphabase serve

# In another terminal, run commands that attach to it
alphabase run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flags

Flag	Short	Description
`--command`		The command to run, use message for args
`--continue`	`-c`	Continue the last session
`--session`	`-s`	Session ID to continue
`--fork`		Fork the session when continuing (use with `--continue` or `--session`)
`--share`		Share the session
`--model`	`-m`	Model to use in the form of provider/model
`--agent`		Agent to use
`--file`	`-f`	File(s) to attach to message
`--format`		Format: default (formatted) or json (raw JSON events)
`--title`		Title for the session (uses truncated prompt if no value provided)
`--attach`		Attach to a running alphabase server (e.g., http://localhost:4096)
`--port`		Port for the local server (defaults to random port)
`--dir`		Directory to run in (or remote path when using `--attach`)
`--variant`		Model variant (provider-specific reasoning effort)
`--thinking`		Show or hide thinking blocks (default: true)

serve

Start a headless AlphaBase server for API access. Check out the server docs for the full HTTP interface.

alphabase serve

This starts an HTTP server that provides API access to alphabase functionality without the TUI interface. Set ALPHABASE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to alphabase).

Flags

Flag	Description
`--port`	Port to listen on
`--hostname`	Hostname to listen on
`--mdns`	Enable mDNS discovery
`--mdns-domain`	Custom domain name for mDNS service
`--cors`	Additional browser origin(s) to allow CORS
`--tls`	Enable HTTPS with self-signed certificate

runner

Start the persistent runner process (durable queue worker).

alphabase runner

Flags

Flag	Description
`--role`	Runner role: `all`, `api`, or `worker`
`--poll-ms`	Poll interval in milliseconds for background drain loops
`--once`	Drain once and exit

session

Manage AlphaBase sessions.

alphabase session [command]

list

List all AlphaBase sessions.

alphabase session list

Flags

Flag	Short	Description
`--all-projects`	`-a`	List sessions across all projects
`--max-count`	`-n`	Limit to N most recent sessions
`--format`		Output format: table or json (table)

stats

Show token usage and cost statistics for your AlphaBase sessions.

alphabase stats

Flags

Flag	Description
`--days`	Show stats for the last N days (all time)
`--tools`	Number of tools to show (all)
`--models`	Show model usage breakdown (hidden by default). Pass a number to show top N
`--project`	Filter by project (all projects, empty string: current project)

export

Export session data as JSON.

alphabase export [sessionID]

If you don’t provide a session ID, you’ll be prompted to select from available sessions.

import

Import session data from a JSON file or AlphaBase share URL.

alphabase import <file>

You can import from a local file or an AlphaBase share URL.

alphabase import session.json
alphabase import https://opncd.ai/s/abc123

pr

Fetch and checkout a GitHub PR branch, then launch alphabase.

alphabase pr <number>

web

Start a headless AlphaBase server with a web interface.

alphabase web

This starts an HTTP server and opens a web browser to access AlphaBase through a web interface. Set ALPHABASE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to alphabase).

Flags

Flag	Description
`--port`	Port to listen on
`--hostname`	Hostname to listen on
`--mdns`	Enable mDNS discovery
`--mdns-domain`	Custom domain name for mDNS service
`--cors`	Additional browser origin(s) to allow CORS
`--tls`	Enable HTTPS with self-signed certificate

acp

Start an ACP (Agent Client Protocol) server.

alphabase acp

This command starts an ACP server that communicates via stdin/stdout using nd-JSON.

Flags

Flag	Description
`--cwd`	Working directory
`--port`	Port to listen on
`--hostname`	Hostname to listen on

uninstall

Uninstall AlphaBase and remove all related files.

alphabase uninstall

Flags

Flag	Short	Description
`--keep-config`	`-c`	Keep configuration files
`--keep-data`	`-d`	Keep session data and snapshots
`--dry-run`		Show what would be removed without removing
`--force`	`-f`	Skip confirmation prompts

upgrade

Updates alphabase to the latest version or a specific version.

alphabase upgrade [target]

To upgrade to the latest version.

alphabase upgrade

To upgrade to a specific version.

alphabase upgrade v0.1.48

Flags

Flag	Short	Description
`--method`	`-m`	The installation method that was used; curl, npm, pnpm, bun, brew

Global Flags

The alphabase CLI takes the following global flags.

Flag	Short	Description
`--help`	`-h`	Display help
`--version`	`-v`	Print version number
`--print-logs`		Print logs to stderr
`--log-level`		Log level (DEBUG, INFO, WARN, ERROR)

Environment variables

AlphaBase can be configured using environment variables.

Variable	Type	Description
`ALPHABASE_AUTO_SHARE`	boolean	Automatically share sessions
`ALPHABASE_GIT_BASH_PATH`	string	Path to Git Bash executable on Windows
`ALPHABASE_CONFIG`	string	Path to config file
`ALPHABASE_CONFIG_DIR`	string	Path to config directory
`ALPHABASE_CONFIG_CONTENT`	string	Inline json config content
`ALPHABASE_DISABLE_AUTOUPDATE`	boolean	Disable automatic update checks
`ALPHABASE_DISABLE_PRUNE`	boolean	Disable pruning of old data
`ALPHABASE_DISABLE_TERMINAL_TITLE`	boolean	Disable automatic terminal title updates
`ALPHABASE_PERMISSION`	string	Inlined json permissions config
`ALPHABASE_DISABLE_DEFAULT_PLUGINS`	boolean	Disable default plugins
`ALPHABASE_DISABLE_LSP_DOWNLOAD`	boolean	Disable automatic LSP server downloads
`ALPHABASE_ENABLE_EXPERIMENTAL_MODELS`	boolean	Enable experimental models
`ALPHABASE_DISABLE_AUTOCOMPACT`	boolean	Disable automatic context compaction
`ALPHABASE_DISABLE_CLAUDE_CODE`	boolean	Disable reading from `.claude` (prompt + skills)
`ALPHABASE_DISABLE_CLAUDE_CODE_PROMPT`	boolean	Disable reading `~/.claude/CLAUDE.md`
`ALPHABASE_DISABLE_CLAUDE_CODE_SKILLS`	boolean	Disable loading `.claude/skills`
`ALPHABASE_DISABLE_MODELS_FETCH`	boolean	Disable fetching models from remote sources
`ALPHABASE_FAKE_VCS`	string	Fake VCS provider for testing purposes
`ALPHABASE_DISABLE_FILETIME_CHECK`	boolean	Disable file time checking for optimization
`ALPHABASE_CLIENT`	string	Client identifier (defaults to `cli`)
`ALPHABASE_ENABLE_EXA`	boolean	Enable Exa web search tools
`ALPHABASE_SERVER_PASSWORD`	string	Enable basic auth for `serve`/`web`
`ALPHABASE_SERVER_USERNAME`	string	Override basic auth username (default `alphabase`)
`ALPHABASE_MODELS_URL`	string	Custom URL for fetching models configuration
`ALPHABASE_GITHUB_ACTION_REPO`	string	GitHub action repo path used by `alphabase github install`

Experimental

These environment variables enable experimental features that may change or be removed.

Variable	Type	Description
`ALPHABASE_EXPERIMENTAL`	boolean	Enable all experimental features
`ALPHABASE_EXPERIMENTAL_ICON_DISCOVERY`	boolean	Enable icon discovery
`ALPHABASE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT`	boolean	Disable copy on select in TUI
`ALPHABASE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS`	number	Default timeout for bash commands in ms
`ALPHABASE_EXPERIMENTAL_OUTPUT_TOKEN_MAX`	number	Max output tokens for LLM responses
`ALPHABASE_EXPERIMENTAL_FILEWATCHER`	boolean	Enable file watcher for entire dir
`ALPHABASE_EXPERIMENTAL_OXFMT`	boolean	Enable oxfmt formatter
`ALPHABASE_EXPERIMENTAL_LSP_TOOL`	boolean	Enable experimental LSP tool
`ALPHABASE_EXPERIMENTAL_DISABLE_FILEWATCHER`	boolean	Disable file watcher
`ALPHABASE_EXPERIMENTAL_EXA`	boolean	Enable experimental Exa features
`ALPHABASE_EXPERIMENTAL_LSP_TY`	boolean	Enable experimental LSP type checking
`ALPHABASE_EXPERIMENTAL_MARKDOWN`	boolean	Enable experimental markdown features
`ALPHABASE_EXPERIMENTAL_PLAN_MODE`	boolean	Enable plan mode