CLI
AicippY CLI options and commands.
The AicippY CLI by default starts the TUI when run without any arguments.
aicippy-codeBut it also accepts commands as documented on this page. This allows you to interact with AicippY programmatically.
aicippy-code run "Explain how closures work in JavaScript"tui
Start the AicippY terminal user interface.
aicippy-code [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 | |
--auto | Auto-approve permissions that are not explicitly denied | |
--port | Port to listen on | |
--hostname | Hostname to listen on | |
--mdns | Enable mDNS discovery | |
--mdns-domain | Custom mDNS domain name | |
--cors | Additional browser origin(s) to allow CORS |
Commands
The AicippY CLI also has the following commands.
agent
Manage agents for AicippY.
aicippy-code agent [command]create
Create a new agent with custom configuration.
aicippy-code agent createThis command will guide you through creating a new agent with a custom system prompt and permission configuration. Anything you don’t allow is denied in the generated agent’s frontmatter.
Flags
| Flag | Short | Description |
|---|---|---|
--path | Directory to write the agent file to (defaults to global or .aicippy-code/agent based on the prompt) | |
--description | What the agent should do | |
--mode | Agent mode: all, primary, or subagent | |
--permissions | Comma-separated list of permissions to allow (default: all). Available: bash, read, edit, glob, grep, webfetch, task, todowrite, websearch, lsp, skill. Anything omitted is denied. Alias: --tools | |
--model | -m | Model to use, in provider/model format |
Passing all of --path, --description, --mode, and --permissions runs the command non-interactively.
list
List all available agents.
aicippy-code agent listattach
Attach a terminal to an already running AicippY backend server started via serve or web commands.
aicippy-code attach [url]This allows using the TUI with a remote AicippY backend. For example:
# Start the backend server for web/mobile accessaicippy-code web --port 4096 --hostname 0.0.0.0
# In another terminal, attach the TUI to the running backendaicippy-code attach http://10.20.30.40:4096Flags
| Flag | Short | Description |
|---|---|---|
--dir | Working directory to start TUI in | |
--continue | -c | Continue the last session |
--session | -s | Session ID to continue |
--fork | Fork the session when continuing (use with --continue or --session) | |
--password | -p | Basic auth password (defaults to AICIPPY_CODE_SERVER_PASSWORD) |
--username | -u | Basic auth username (defaults to AICIPPY_CODE_SERVER_USERNAME or aicippy-code) |
auth
Command to manage credentials and login for providers.
aicippy-code auth [command]login
AicippY is powered by the provider list at AicippY Models, so you can use aicippy-code auth login to configure API keys for any provider you’d like to use. This is stored in ~/.local/share/aicippy-code/auth.json.
aicippy-code auth loginWhen AicippY 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.
Flags
| Flag | Short | Description |
|---|---|---|
--provider | -p | Provider ID or name to log in to |
--method | -m | Login method label to use, skipping method selection |
list
Lists all the authenticated providers as stored in the credentials file.
aicippy-code auth listOr the short version.
aicippy-code auth lslogout
Logs you out of a provider by clearing it from the credentials file.
aicippy-code auth logoutmcp
Manage Model Context Protocol servers.
aicippy-code mcp [command]add
Add an MCP server to your configuration.
aicippy-code mcp addThis command will guide you through adding either a local or remote MCP server.
list
List all configured MCP servers and their connection status.
aicippy-code mcp listOr use the short version.
aicippy-code mcp lsauth
Authenticate with an OAuth-enabled MCP server.
aicippy-code 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.
aicippy-code mcp auth listOr use the short version.
aicippy-code mcp auth lslogout
Remove OAuth credentials for an MCP server.
aicippy-code mcp logout [name]debug
Debug OAuth connection issues for an MCP server.
aicippy-code mcp debug <name>models
List all available models from configured providers.
aicippy-code 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.
aicippy-code models aicippyFlags
| Flag | Description |
|---|---|
--refresh | Refresh the models cache from models.aicippy.com |
--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 AicippY.
aicippy-code models --refreshrun
Run aicippy-code in non-interactive mode by passing a prompt directly.
aicippy-code run [message..]This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.
aicippy-code run Explain the use of context in GoYou can also attach to a running aicippy-code serve instance to avoid MCP server cold boot times on every run:
# Start a headless server in one terminalaicippy-code serve
# In another terminal, run commands that attach to itaicippy-code 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 aicippy-code server (e.g., http://localhost:4096) | |
--password | -p | Basic auth password (defaults to AICIPPY_CODE_SERVER_PASSWORD) |
--username | -u | Basic auth username (defaults to AICIPPY_CODE_SERVER_USERNAME or aicippy-code) |
--dir | Directory to run in, or path on the remote server when attaching | |
--port | Port for the local server (defaults to random port) | |
--variant | Model variant (provider-specific reasoning effort) | |
--thinking | Show thinking blocks | |
--auto | Auto-approve permissions that are not explicitly denied |
serve
Start a headless AicippY server for API access. Check out the server docs for the full HTTP interface.
aicippy-code serveThis starts an HTTP server that provides API access to aicippy-code functionality without the TUI interface. Set AICIPPY_CODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to aicippy-code).
Flags
| Flag | Description |
|---|---|
--port | Port to listen on |
--hostname | Hostname to listen on |
--mdns | Enable mDNS discovery |
--mdns-domain | Custom mDNS domain name |
--cors | Additional browser origin(s) to allow CORS |
session
Manage AicippY sessions.
aicippy-code session [command]list
List all AicippY sessions.
aicippy-code session listFlags
| Flag | Short | Description |
|---|---|---|
--max-count | -n | Limit to N most recent sessions |
--format | Output format: table or json (table) |
delete
Delete an AicippY session.
aicippy-code session delete <sessionID>stats
Show token usage and cost statistics for your AicippY sessions.
aicippy-code statsFlags
| 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.
aicippy-code export [sessionID]If you don’t provide a session ID, you’ll be prompted to select from available sessions.
Flags
| Flag | Description |
|---|---|
--sanitize | Redact sensitive transcript/file data |
import
Import session data from a JSON file or AicippY share URL.
aicippy-code import <file>You can import from a local file or an AicippY share URL.
aicippy-code import session.jsonaicippy-code import https://www.aicippy.com/share/abc123web
Start a headless AicippY server with a web interface.
aicippy-code webThis starts an HTTP server and opens a web browser to access AicippY through a web interface. Set AICIPPY_CODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to aicippy-code).
Flags
| Flag | Description |
|---|---|
--port | Port to listen on |
--hostname | Hostname to listen on |
--mdns | Enable mDNS discovery |
--mdns-domain | Custom mDNS domain name |
--cors | Additional browser origin(s) to allow CORS |
acp
Start an ACP (Agent Client Protocol) server.
aicippy-code acpThis 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 |
--mdns | Enable mDNS discovery |
--mdns-domain | Custom mDNS domain name |
--cors | Additional browser origin(s) to allow CORS |
plugin
Install a plugin and update your config.
aicippy-code plugin <module>Or use the alias.
aicippy-code plug <module>Flags
| Flag | Short | Description |
|---|---|---|
--global | -g | Install in global config |
--force | -f | Replace existing plugin version |
pr
Fetch and checkout a GitHub PR branch, then run AicippY.
aicippy-code pr <number>db
Database tools.
aicippy-code db [query]Flags
| Flag | Description |
|---|---|
--format | Output format: json or tsv |
path
Print the database path.
aicippy-code db pathdebug
Debugging and troubleshooting tools.
aicippy-code debug [command]uninstall
Uninstall AicippY and remove all related files.
aicippy-code uninstallFlags
| 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 aicippy-code to the latest version or a specific version.
aicippy-code upgrade [target]To upgrade to the latest version.
aicippy-code upgradeTo upgrade to a specific version.
aicippy-code upgrade v0.1.48Flags
| Flag | Short | Description |
|---|---|---|
--method | -m | The installation method that was used; curl, npm, pnpm, bun, brew |
Global flags
The aicippy-code 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) | |
--pure | Run without external plugins |
Environment variables
AicippY can be configured using environment variables.
| Variable | Type | Description |
|---|---|---|
AICIPPY_CODE_AUTO_SHARE | boolean | Automatically share sessions |
AICIPPY_CODE_GIT_BASH_PATH | string | Path to Git Bash executable on Windows |
AICIPPY_CODE_CONFIG | string | Path to config file |
AICIPPY_CODE_TUI_CONFIG | string | Path to TUI config file |
AICIPPY_CODE_CONFIG_DIR | string | Path to config directory |
AICIPPY_CODE_CONFIG_CONTENT | string | Inline json config content |
AICIPPY_CODE_DISABLE_AUTOUPDATE | boolean | Disable automatic update checks |
AICIPPY_CODE_DISABLE_PRUNE | boolean | Disable pruning of old data |
AICIPPY_CODE_DISABLE_TERMINAL_TITLE | boolean | Disable automatic terminal title updates |
AICIPPY_CODE_PERMISSION | string | Inlined json permissions config |
AICIPPY_CODE_DISABLE_DEFAULT_PLUGINS | boolean | Disable default plugins |
AICIPPY_CODE_DISABLE_LSP_DOWNLOAD | boolean | Disable automatic LSP server downloads |
AICIPPY_CODE_ENABLE_EXPERIMENTAL_MODELS | boolean | Enable experimental models |
AICIPPY_CODE_DISABLE_AUTOCOMPACT | boolean | Disable automatic context compaction |
AICIPPY_CODE_DISABLE_CLAUDE_CODE | boolean | Disable reading from .claude (prompt + skills) |
AICIPPY_CODE_DISABLE_CLAUDE_CODE_PROMPT | boolean | Disable reading ~/.claude/CLAUDE.md |
AICIPPY_CODE_DISABLE_CLAUDE_CODE_SKILLS | boolean | Disable loading .claude/skills |
AICIPPY_CODE_DISABLE_MODELS_FETCH | boolean | Disable fetching models from remote sources |
AICIPPY_CODE_DISABLE_MOUSE | boolean | Disable mouse capture in the TUI |
AICIPPY_CODE_FAKE_VCS | string | Fake VCS provider for testing purposes |
AICIPPY_CODE_CLIENT | string | Client identifier (defaults to cli) |
AICIPPY_CODE_ENABLE_EXA | boolean | Enable Exa web search tools |
AICIPPY_CODE_ENABLE_PARALLEL | boolean | Enable Parallel web search tools |
AICIPPY_CODE_SERVER_PASSWORD | string | Enable basic auth for serve/web |
AICIPPY_CODE_SERVER_USERNAME | string | Override basic auth username (default aicippy-code) |
AICIPPY_CODE_MODELS_URL | string | Custom URL for fetching models configuration |
Experimental
These environment variables enable experimental features that may change or be removed.
| Variable | Type | Description |
|---|---|---|
AICIPPY_CODE_EXPERIMENTAL | boolean | Enable the experimental umbrella flag |
AICIPPY_CODE_EXPERIMENTAL_ICON_DISCOVERY | boolean | Enable icon discovery |
AICIPPY_CODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT | boolean | Disable copy on select in TUI |
AICIPPY_CODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS | number | Default timeout for bash commands in ms |
AICIPPY_CODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX | number | Max output tokens for LLM responses |
AICIPPY_CODE_EXPERIMENTAL_FILEWATCHER | boolean | Enable file watcher for entire dir |
AICIPPY_CODE_EXPERIMENTAL_OXFMT | boolean | Enable oxfmt formatter |
AICIPPY_CODE_EXPERIMENTAL_LSP_TOOL | boolean | Enable experimental LSP tool |
AICIPPY_CODE_EXPERIMENTAL_DISABLE_FILEWATCHER | boolean | Disable file watcher |
AICIPPY_CODE_EXPERIMENTAL_EXA | boolean | Enable experimental Exa features |
AICIPPY_CODE_EXPERIMENTAL_LSP_TY | boolean | Enable TY LSP for python files |
AICIPPY_CODE_EXPERIMENTAL_PLAN_MODE | boolean | Enable plan mode |
AICIPPY_CODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS | boolean | Enable background subagent tasks |
AICIPPY_CODE_EXPERIMENTAL_EVENT_SYSTEM | boolean | Enable experimental event system |
AICIPPY_CODE_EXPERIMENTAL_NATIVE_LLM | boolean | Enable native LLM request path |
AICIPPY_CODE_EXPERIMENTAL_PARALLEL | boolean | Enable parallel web search execution |
AICIPPY_CODE_EXPERIMENTAL_SCOUT | boolean | Enable Scout subagent |
AICIPPY_CODE_EXPERIMENTAL_WORKSPACES | boolean | Enable workspace support |
Last updated: