Skip to content
Login

CLI

AicippY CLI options and commands.

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

Terminal window
aicippy-code

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

Terminal window
aicippy-code run "Explain how closures work in JavaScript"

tui

Start the AicippY terminal user interface.

Terminal window
aicippy-code [project]

Flags

FlagShortDescription
--continue-cContinue the last session
--session-sSession ID to continue
--forkFork the session when continuing (use with --continue or --session)
--promptPrompt to use
--model-mModel to use in the form of provider/model
--agentAgent to use
--autoAuto-approve permissions that are not explicitly denied
--portPort to listen on
--hostnameHostname to listen on
--mdnsEnable mDNS discovery
--mdns-domainCustom mDNS domain name
--corsAdditional browser origin(s) to allow CORS

Commands

The AicippY CLI also has the following commands.


agent

Manage agents for AicippY.

Terminal window
aicippy-code agent [command]

create

Create a new agent with custom configuration.

Terminal window
aicippy-code agent create

This 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

FlagShortDescription
--pathDirectory to write the agent file to (defaults to global or .aicippy-code/agent based on the prompt)
--descriptionWhat the agent should do
--modeAgent mode: all, primary, or subagent
--permissionsComma-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-mModel to use, in provider/model format

Passing all of --path, --description, --mode, and --permissions runs the command non-interactively.


list

List all available agents.

Terminal window
aicippy-code agent list

attach

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

Terminal window
aicippy-code attach [url]

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

Terminal window
# Start the backend server for web/mobile access
aicippy-code web --port 4096 --hostname 0.0.0.0
# In another terminal, attach the TUI to the running backend
aicippy-code attach http://10.20.30.40:4096

Flags

FlagShortDescription
--dirWorking directory to start TUI in
--continue-cContinue the last session
--session-sSession ID to continue
--forkFork the session when continuing (use with --continue or --session)
--password-pBasic auth password (defaults to AICIPPY_CODE_SERVER_PASSWORD)
--username-uBasic auth username (defaults to AICIPPY_CODE_SERVER_USERNAME or aicippy-code)

auth

Command to manage credentials and login for providers.

Terminal window
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.

Terminal window
aicippy-code auth login

When 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
FlagShortDescription
--provider-pProvider ID or name to log in to
--method-mLogin method label to use, skipping method selection

list

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

Terminal window
aicippy-code auth list

Or the short version.

Terminal window
aicippy-code auth ls

logout

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

Terminal window
aicippy-code auth logout

mcp

Manage Model Context Protocol servers.

Terminal window
aicippy-code mcp [command]

add

Add an MCP server to your configuration.

Terminal window
aicippy-code 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.

Terminal window
aicippy-code mcp list

Or use the short version.

Terminal window
aicippy-code mcp ls

auth

Authenticate with an OAuth-enabled MCP server.

Terminal window
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.

Terminal window
aicippy-code mcp auth list

Or use the short version.

Terminal window
aicippy-code mcp auth ls

logout

Remove OAuth credentials for an MCP server.

Terminal window
aicippy-code mcp logout [name]

debug

Debug OAuth connection issues for an MCP server.

Terminal window
aicippy-code mcp debug <name>

models

List all available models from configured providers.

Terminal window
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.

Terminal window
aicippy-code models aicippy

Flags

FlagDescription
--refreshRefresh the models cache from models.aicippy.com
--verboseUse 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.

Terminal window
aicippy-code models --refresh

run

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

Terminal window
aicippy-code run [message..]

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

Terminal window
aicippy-code run Explain the use of context in Go

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

Terminal window
# Start a headless server in one terminal
aicippy-code serve
# In another terminal, run commands that attach to it
aicippy-code run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flags

FlagShortDescription
--commandThe command to run, use message for args
--continue-cContinue the last session
--session-sSession ID to continue
--forkFork the session when continuing (use with --continue or --session)
--shareShare the session
--model-mModel to use in the form of provider/model
--agentAgent to use
--file-fFile(s) to attach to message
--formatFormat: default (formatted) or json (raw JSON events)
--titleTitle for the session (uses truncated prompt if no value provided)
--attachAttach to a running aicippy-code server (e.g., http://localhost:4096)
--password-pBasic auth password (defaults to AICIPPY_CODE_SERVER_PASSWORD)
--username-uBasic auth username (defaults to AICIPPY_CODE_SERVER_USERNAME or aicippy-code)
--dirDirectory to run in, or path on the remote server when attaching
--portPort for the local server (defaults to random port)
--variantModel variant (provider-specific reasoning effort)
--thinkingShow thinking blocks
--autoAuto-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.

Terminal window
aicippy-code serve

This 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

FlagDescription
--portPort to listen on
--hostnameHostname to listen on
--mdnsEnable mDNS discovery
--mdns-domainCustom mDNS domain name
--corsAdditional browser origin(s) to allow CORS

session

Manage AicippY sessions.

Terminal window
aicippy-code session [command]

list

List all AicippY sessions.

Terminal window
aicippy-code session list
Flags
FlagShortDescription
--max-count-nLimit to N most recent sessions
--formatOutput format: table or json (table)

delete

Delete an AicippY session.

Terminal window
aicippy-code session delete <sessionID>

stats

Show token usage and cost statistics for your AicippY sessions.

Terminal window
aicippy-code stats

Flags

FlagDescription
--daysShow stats for the last N days (all time)
--toolsNumber of tools to show (all)
--modelsShow model usage breakdown (hidden by default). Pass a number to show top N
--projectFilter by project (all projects, empty string: current project)

export

Export session data as JSON.

Terminal window
aicippy-code export [sessionID]

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

Flags

FlagDescription
--sanitizeRedact sensitive transcript/file data

import

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

Terminal window
aicippy-code import <file>

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

Terminal window
aicippy-code import session.json
aicippy-code import https://www.aicippy.com/share/abc123

web

Start a headless AicippY server with a web interface.

Terminal window
aicippy-code web

This 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

FlagDescription
--portPort to listen on
--hostnameHostname to listen on
--mdnsEnable mDNS discovery
--mdns-domainCustom mDNS domain name
--corsAdditional browser origin(s) to allow CORS

acp

Start an ACP (Agent Client Protocol) server.

Terminal window
aicippy-code acp

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

Flags

FlagDescription
--cwdWorking directory
--portPort to listen on
--hostnameHostname to listen on
--mdnsEnable mDNS discovery
--mdns-domainCustom mDNS domain name
--corsAdditional browser origin(s) to allow CORS

plugin

Install a plugin and update your config.

Terminal window
aicippy-code plugin <module>

Or use the alias.

Terminal window
aicippy-code plug <module>

Flags

FlagShortDescription
--global-gInstall in global config
--force-fReplace existing plugin version

pr

Fetch and checkout a GitHub PR branch, then run AicippY.

Terminal window
aicippy-code pr <number>

db

Database tools.

Terminal window
aicippy-code db [query]

Flags

FlagDescription
--formatOutput format: json or tsv

path

Print the database path.

Terminal window
aicippy-code db path

debug

Debugging and troubleshooting tools.

Terminal window
aicippy-code debug [command]

uninstall

Uninstall AicippY and remove all related files.

Terminal window
aicippy-code uninstall

Flags

FlagShortDescription
--keep-config-cKeep configuration files
--keep-data-dKeep session data and snapshots
--dry-runShow what would be removed without removing
--force-fSkip confirmation prompts

upgrade

Updates aicippy-code to the latest version or a specific version.

Terminal window
aicippy-code upgrade [target]

To upgrade to the latest version.

Terminal window
aicippy-code upgrade

To upgrade to a specific version.

Terminal window
aicippy-code upgrade v0.1.48

Flags

FlagShortDescription
--method-mThe installation method that was used; curl, npm, pnpm, bun, brew

Global flags

The aicippy-code CLI takes the following global flags.

FlagShortDescription
--help-hDisplay help
--version-vPrint version number
--print-logsPrint logs to stderr
--log-levelLog level (DEBUG, INFO, WARN, ERROR)
--pureRun without external plugins

Environment variables

AicippY can be configured using environment variables.

VariableTypeDescription
AICIPPY_CODE_AUTO_SHAREbooleanAutomatically share sessions
AICIPPY_CODE_GIT_BASH_PATHstringPath to Git Bash executable on Windows
AICIPPY_CODE_CONFIGstringPath to config file
AICIPPY_CODE_TUI_CONFIGstringPath to TUI config file
AICIPPY_CODE_CONFIG_DIRstringPath to config directory
AICIPPY_CODE_CONFIG_CONTENTstringInline json config content
AICIPPY_CODE_DISABLE_AUTOUPDATEbooleanDisable automatic update checks
AICIPPY_CODE_DISABLE_PRUNEbooleanDisable pruning of old data
AICIPPY_CODE_DISABLE_TERMINAL_TITLEbooleanDisable automatic terminal title updates
AICIPPY_CODE_PERMISSIONstringInlined json permissions config
AICIPPY_CODE_DISABLE_DEFAULT_PLUGINSbooleanDisable default plugins
AICIPPY_CODE_DISABLE_LSP_DOWNLOADbooleanDisable automatic LSP server downloads
AICIPPY_CODE_ENABLE_EXPERIMENTAL_MODELSbooleanEnable experimental models
AICIPPY_CODE_DISABLE_AUTOCOMPACTbooleanDisable automatic context compaction
AICIPPY_CODE_DISABLE_CLAUDE_CODEbooleanDisable reading from .claude (prompt + skills)
AICIPPY_CODE_DISABLE_CLAUDE_CODE_PROMPTbooleanDisable reading ~/.claude/CLAUDE.md
AICIPPY_CODE_DISABLE_CLAUDE_CODE_SKILLSbooleanDisable loading .claude/skills
AICIPPY_CODE_DISABLE_MODELS_FETCHbooleanDisable fetching models from remote sources
AICIPPY_CODE_DISABLE_MOUSEbooleanDisable mouse capture in the TUI
AICIPPY_CODE_FAKE_VCSstringFake VCS provider for testing purposes
AICIPPY_CODE_CLIENTstringClient identifier (defaults to cli)
AICIPPY_CODE_ENABLE_EXAbooleanEnable Exa web search tools
AICIPPY_CODE_ENABLE_PARALLELbooleanEnable Parallel web search tools
AICIPPY_CODE_SERVER_PASSWORDstringEnable basic auth for serve/web
AICIPPY_CODE_SERVER_USERNAMEstringOverride basic auth username (default aicippy-code)
AICIPPY_CODE_MODELS_URLstringCustom URL for fetching models configuration

Experimental

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

VariableTypeDescription
AICIPPY_CODE_EXPERIMENTALbooleanEnable the experimental umbrella flag
AICIPPY_CODE_EXPERIMENTAL_ICON_DISCOVERYbooleanEnable icon discovery
AICIPPY_CODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECTbooleanDisable copy on select in TUI
AICIPPY_CODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MSnumberDefault timeout for bash commands in ms
AICIPPY_CODE_EXPERIMENTAL_OUTPUT_TOKEN_MAXnumberMax output tokens for LLM responses
AICIPPY_CODE_EXPERIMENTAL_FILEWATCHERbooleanEnable file watcher for entire dir
AICIPPY_CODE_EXPERIMENTAL_OXFMTbooleanEnable oxfmt formatter
AICIPPY_CODE_EXPERIMENTAL_LSP_TOOLbooleanEnable experimental LSP tool
AICIPPY_CODE_EXPERIMENTAL_DISABLE_FILEWATCHERbooleanDisable file watcher
AICIPPY_CODE_EXPERIMENTAL_EXAbooleanEnable experimental Exa features
AICIPPY_CODE_EXPERIMENTAL_LSP_TYbooleanEnable TY LSP for python files
AICIPPY_CODE_EXPERIMENTAL_PLAN_MODEbooleanEnable plan mode
AICIPPY_CODE_EXPERIMENTAL_BACKGROUND_SUBAGENTSbooleanEnable background subagent tasks
AICIPPY_CODE_EXPERIMENTAL_EVENT_SYSTEMbooleanEnable experimental event system
AICIPPY_CODE_EXPERIMENTAL_NATIVE_LLMbooleanEnable native LLM request path
AICIPPY_CODE_EXPERIMENTAL_PARALLELbooleanEnable parallel web search execution
AICIPPY_CODE_EXPERIMENTAL_SCOUTbooleanEnable Scout subagent
AICIPPY_CODE_EXPERIMENTAL_WORKSPACESbooleanEnable workspace support

Last updated: