Configuration
Config - CLI

CLI Options Reference

You can use cecli --help to see all the available options, or review them below.

Tip:
See the API key configuration docs for information on how to configure and store your API keys.

Usage summary

usage: cecli [-h] [--model] [--openai-api-key] [--anthropic-api-key]
             [--openai-api-base] [--openai-api-type]
             [--openai-api-version] [--openai-api-deployment-id]
             [--openai-organization-id] [--set-env] [--api-key]
             [--list-models] [--model-settings-file]
             [--model-metadata-file] [--alias] [--reasoning-effort]
             [--thinking-tokens] [--verify-ssl | --no-verify-ssl]
             [--timeout] [--edit-format] [--architect]
             [--auto-accept-architect | --no-auto-accept-architect]
             [--weak-model] [--editor-model] [--editor-edit-format]
             [--show-model-warnings | --no-show-model-warnings]
             [--check-model-accepts-settings | --no-check-model-accepts-settings]
             [--max-chat-history-tokens]
             [--enable-context-compaction | --no-enable-context-compaction]
             [--context-compaction-max-tokens]
             [--context-compaction-summary-tokens]
             [--cache-prompts | --no-cache-prompts]
             [--cache-keepalive-pings] [--map-tokens]
             [--map-refresh] [--map-multiplier-no-files]
             [--input-history-file] [--chat-history-file]
             [--restore-chat-history | --no-restore-chat-history]
             [--llm-history-file] [--dark-mode] [--light-mode]
             [--pretty | --no-pretty] [--stream | --no-stream]
             [--user-input-color] [--tool-output-color]
             [--tool-error-color] [--tool-warning-color]
             [--assistant-output-color] [--completion-menu-color]
             [--completion-menu-bg-color]
             [--completion-menu-current-color]
             [--completion-menu-current-bg-color] [--code-theme]
             [--show-diffs] [--git | --no-git]
             [--gitignore | --no-gitignore]
             [--add-gitignore-files | --no-add-gitignore-files]
             [--aiderignore] [--subtree-only]
             [--auto-commits | --no-auto-commits]
             [--dirty-commits | --no-dirty-commits]
             [--attribute-author | --no-attribute-author]
             [--attribute-committer | --no-attribute-committer]
             [--attribute-commit-message-author | --no-attribute-commit-message-author]
             [--attribute-commit-message-committer | --no-attribute-commit-message-committer]
             [--attribute-co-authored-by | --no-attribute-co-authored-by]
             [--git-commit-verify | --no-git-commit-verify]
             [--commit] [--commit-prompt] [--dry-run | --no-dry-run]
             [--skip-sanity-check-repo]
             [--watch-files | --no-watch-files] [--lint]
             [--lint-cmd] [--auto-lint | --no-auto-lint]
             [--test-cmd] [--auto-test | --no-auto-test] [--test]
             [--just-check-update]
             [--check-update | --no-check-update]
             [--show-release-notes | --no-show-release-notes]
             [--install-main-branch] [--upgrade] [--version]
             [--message] [--message-file]
             [--gui | --no-gui | --browser | --no-browser]
             [--copy-paste | --no-copy-paste] [--apply]
             [--apply-clipboard-edits] [--exit] [--show-repo-map]
             [--show-prompts] [--voice-format] [--voice-language]
             [--voice-input-device] [--disable-playwright] [--file]
             [--read] [--vim] [--chat-language] [--commit-language]
             [--yes-always] [-v] [--load] [--encoding]
             [--line-endings] [-c] [--env-file]
             [--suggest-shell-commands | --no-suggest-shell-commands]
             [--fancy-input | --no-fancy-input]
             [--multiline | --no-multiline]
             [--notifications | --no-notifications]
             [--notifications-command]
             [--detect-urls | --no-detect-urls] [--editor]
             [--shell-completions] [--opus] [--sonnet] [--haiku]
             [--4] [--4o] [--mini] [--4-turbo] [--35turbo]
             [--deepseek] [--o1-mini] [--o1-preview]

options:

`--help`

show this help message and exit Aliases:

-h
--help

Main model:

`--model MODEL`

Specify the model to use for the main chat Environment variable: CECLI_MODEL

API Keys and settings:

`--openai-api-key VALUE`

Specify the OpenAI API key Environment variable: CECLI_OPENAI_API_KEY

`--anthropic-api-key VALUE`

Specify the Anthropic API key Environment variable: CECLI_ANTHROPIC_API_KEY

`--openai-api-base VALUE`

Specify the api base url Environment variable: CECLI_OPENAI_API_BASE

`--openai-api-type VALUE`

(deprecated, use --set-env OPENAI_API_TYPE=<value>) Environment variable: CECLI_OPENAI_API_TYPE

`--openai-api-version VALUE`

(deprecated, use --set-env OPENAI_API_VERSION=<value>) Environment variable: CECLI_OPENAI_API_VERSION

`--openai-api-deployment-id VALUE`

(deprecated, use --set-env OPENAI_API_DEPLOYMENT_ID=<value>) Environment variable: CECLI_OPENAI_API_DEPLOYMENT_ID

`--openai-organization-id VALUE`

(deprecated, use --set-env OPENAI_ORGANIZATION=<value>) Environment variable: CECLI_OPENAI_ORGANIZATION_ID

`--set-env ENV_VAR_NAME=value`

Set an environment variable (to control API settings, can be used multiple times) Default: [] Environment variable: CECLI_SET_ENV

`--api-key PROVIDER=KEY`

Set an API key for a provider (eg: --api-key provider=<key> sets PROVIDER_API_KEY=<key>) Default: [] Environment variable: CECLI_API_KEY

Model settings:

`--list-models MODEL`

List known models which match the (partial) MODEL name Environment variable: CECLI_LIST_MODELS Aliases:

--list-models MODEL
--models MODEL

`--model-settings-file MODEL_SETTINGS_FILE`

Specify a file with cecli model settings for unknown models Default: .cecli.model.settings.yml Environment variable: CECLI_MODEL_SETTINGS_FILE

`--model-metadata-file MODEL_METADATA_FILE`

Specify a file with context window and costs for unknown models Default: .cecli.model.metadata.json Environment variable: CECLI_MODEL_METADATA_FILE

`--alias ALIAS:MODEL`

Add a model alias (can be used multiple times) Environment variable: CECLI_ALIAS

`--reasoning-effort VALUE`

Set the reasoning_effort API parameter (default: not set) Environment variable: CECLI_REASONING_EFFORT

`--thinking-tokens VALUE`

Set the thinking token budget for models that support it. Use 0 to disable. (default: not set) Environment variable: CECLI_THINKING_TOKENS

`--verify-ssl`

Verify the SSL cert when connecting to models (default: True) Default: True Environment variable: CECLI_VERIFY_SSL Aliases:

--verify-ssl
--no-verify-ssl

`--timeout VALUE`

Timeout in seconds for API calls (default: None) Environment variable: CECLI_TIMEOUT

`--edit-format EDIT_FORMAT`

Specify what edit format the LLM should use (default depends on model) Environment variable: CECLI_EDIT_FORMAT Aliases:

--edit-format EDIT_FORMAT
--chat-mode EDIT_FORMAT

`--architect`

Use architect edit format for the main chat Environment variable: CECLI_ARCHITECT

`--auto-accept-architect`

Enable/disable automatic acceptance of architect changes (default: True) Default: True Environment variable: CECLI_AUTO_ACCEPT_ARCHITECT Aliases:

--auto-accept-architect
--no-auto-accept-architect

`--weak-model WEAK_MODEL`

Specify the model to use for commit messages and chat history summarization (default depends on --model) Environment variable: CECLI_WEAK_MODEL

`--editor-model EDITOR_MODEL`

Specify the model to use for editor tasks (default depends on --model) Environment variable: CECLI_EDITOR_MODEL

`--editor-edit-format EDITOR_EDIT_FORMAT`

Specify the edit format for the editor model (default: depends on editor model) Environment variable: CECLI_EDITOR_EDIT_FORMAT

`--show-model-warnings`

Only work with models that have meta-data available (default: True) Default: True Environment variable: CECLI_SHOW_MODEL_WARNINGS Aliases:

--show-model-warnings
--no-show-model-warnings

`--check-model-accepts-settings`

Check if model accepts settings like reasoning_effort/thinking_tokens (default: True) Default: True Environment variable: CECLI_CHECK_MODEL_ACCEPTS_SETTINGS Aliases:

--check-model-accepts-settings
--no-check-model-accepts-settings

`--max-chat-history-tokens VALUE`

Soft limit on tokens for chat history, after which summarization begins. If unspecified, defaults to the model’s max_chat_history_tokens. Environment variable: CECLI_MAX_CHAT_HISTORY_TOKENS

Context Compaction:

`--enable-context-compaction`

Enable automatic compaction of chat history to conserve tokens (default: False) Default: False Environment variable: CECLI_ENABLE_CONTEXT_COMPACTION Aliases:

--enable-context-compaction
--no-enable-context-compaction

`--context-compaction-max-tokens VALUE`

The maximum number of tokens in the conversation before context compaction is triggered. (default: 80% of model’s context window) Environment variable: CECLI_CONTEXT_COMPACTION_MAX_TOKENS

`--context-compaction-summary-tokens VALUE`

The target maximum number of tokens for the generated summary. (default: 4096) Default: 4096 Environment variable: CECLI_CONTEXT_COMPACTION_SUMMARY_TOKENS

`--max-compaction-retries VALUE`

Maximum number of automatic compaction and retry attempts when a context window error occurs (default: 3, range: 1-10). In agent mode, this is capped at 2 retries for safety. Default: 3 Environment variable: CECLI_MAX_COMPACTION_RETRIES

Cache settings:

`--cache-prompts`

Enable caching of prompts (default: False) Default: False Environment variable: CECLI_CACHE_PROMPTS Aliases:

--cache-prompts
--no-cache-prompts

`--cache-keepalive-pings VALUE`

Number of times to ping at 5min intervals to keep prompt cache warm (default: 0) Default: 0 Environment variable: CECLI_CACHE_KEEPALIVE_PINGS

Repomap settings:

`--map-tokens VALUE`

Suggested number of tokens to use for repo map, use 0 to disable Environment variable: CECLI_MAP_TOKENS

`--map-refresh VALUE`

Control how often the repo map is refreshed. Options: auto, always, files, manual (default: auto) Default: auto Environment variable: CECLI_MAP_REFRESH

`--map-multiplier-no-files VALUE`

Multiplier for map tokens when no files are specified (default: 2) Default: 2 Environment variable: CECLI_MAP_MULTIPLIER_NO_FILES

`--map-max-line-length VALUE`

Maximum line length for the repo map code. Prevents sending crazy long lines of minified JS files etc. (default: 100) Default: 100 Environment variable: CECLI_MAP_MAX_LINE_LENGTH

History Files:

`--input-history-file INPUT_HISTORY_FILE`

Specify the chat input history file (default: .cecli.input.history) Default: .cecli.input.history Environment variable: CECLI_INPUT_HISTORY_FILE

`--chat-history-file CHAT_HISTORY_FILE`

Specify the chat history file (default: .cecli.dev.history.md) Default: .cecli.dev.history.md Environment variable: CECLI_CHAT_HISTORY_FILE

`--restore-chat-history`

Restore the previous chat history messages (default: False) Default: False Environment variable: CECLI_RESTORE_CHAT_HISTORY Aliases:

--restore-chat-history
--no-restore-chat-history

`--llm-history-file LLM_HISTORY_FILE`

Log the conversation with the LLM to this file (for example, .cecli.llm.history) Environment variable: CECLI_LLM_HISTORY_FILE

Output settings:

`--dark-mode`

Use colors suitable for a dark terminal background (default: False) Default: False Environment variable: CECLI_DARK_MODE

`--light-mode`

Use colors suitable for a light terminal background (default: False) Default: False Environment variable: CECLI_LIGHT_MODE

`--pretty`

Enable/disable pretty, colorized output (default: True) Default: True Environment variable: CECLI_PRETTY Aliases:

--pretty
--no-pretty

`--stream`

Enable/disable streaming responses (default: True) Default: True Environment variable: CECLI_STREAM Aliases:

--stream
--no-stream

`--spinner`

Enable/disable the spinner while waiting for LLM responses (default: True) Default: True Environment variable: CECLI_SPINNER Aliases:

--spinner
--no-spinner

`--user-input-color VALUE`

Set the color for user input (default: #00cc00) Default: #00cc00 Environment variable: CECLI_USER_INPUT_COLOR

`--tool-output-color VALUE`

Set the color for tool output (default: None) Environment variable: CECLI_TOOL_OUTPUT_COLOR

`--tool-error-color VALUE`

Set the color for tool error messages (default: #FF2222) Default: #FF2222 Environment variable: CECLI_TOOL_ERROR_COLOR

`--tool-warning-color VALUE`

Set the color for tool warning messages (default: #FFA500) Default: #FFA500 Environment variable: CECLI_TOOL_WARNING_COLOR

`--assistant-output-color VALUE`

Set the color for assistant output (default: #0088ff) Default: #0088ff Environment variable: CECLI_ASSISTANT_OUTPUT_COLOR

`--completion-menu-color COLOR`

Set the color for the completion menu (default: terminal’s default text color) Environment variable: CECLI_COMPLETION_MENU_COLOR

`--completion-menu-bg-color COLOR`

Set the background color for the completion menu (default: terminal’s default background color) Environment variable: CECLI_COMPLETION_MENU_BG_COLOR

`--completion-menu-current-color COLOR`

Set the color for the current item in the completion menu (default: terminal’s default background color) Environment variable: CECLI_COMPLETION_MENU_CURRENT_COLOR

`--completion-menu-current-bg-color COLOR`

Set the background color for the current item in the completion menu (default: terminal’s default text color) Environment variable: CECLI_COMPLETION_MENU_CURRENT_BG_COLOR

`--code-theme VALUE`

Set the markdown code theme (default: default, other options include monokai, solarized-dark, solarized-light, or a Pygments builtin style, see https://pygments.org/styles for available themes) Default: default Environment variable: CECLI_CODE_THEME

`--show-diffs`

Show diffs when committing changes (default: False) Default: False Environment variable: CECLI_SHOW_DIFFS

Git settings:

`--git`

Enable/disable looking for a git repo (default: True) Default: True Environment variable: CECLI_GIT Aliases:

--git
--no-git

`--gitignore`

Enable/disable adding .cecli* to .gitignore (default: True) Default: True Environment variable: CECLI_GITIGNORE Aliases:

--gitignore
--no-gitignore

`--add-gitignore-files`

Enable/disable the addition of files listed in .gitignore to cecli’s editing scope. Default: False Environment variable: CECLI_ADD_GITIGNORE_FILES Aliases:

--add-gitignore-files
--no-add-gitignore-files

`--cecli-ignore CECLI_IGNORE`

Specify the cecli ignore file (default: .cecli.ignore in git root) Default: .cecli.ignore Environment variable: CECLI_IGNORE

`--subtree-only`

Only consider files in the current subtree of the git repository Default: False Environment variable: CECLI_SUBTREE_ONLY

`--auto-commits`

Enable/disable auto commit of LLM changes (default: True) Default: True Environment variable: CECLI_AUTO_COMMITS Aliases:

--auto-commits
--no-auto-commits

`--dirty-commits`

Enable/disable commits when repo is found dirty (default: True) Default: True Environment variable: CECLI_DIRTY_COMMITS Aliases:

--dirty-commits
--no-dirty-commits

`--attribute-author`

Attribute cecli code changes in the git author name (default: True). If explicitly set to True, overrides --attribute-co-authored-by precedence. Environment variable: CECLI_ATTRIBUTE_AUTHOR Aliases:

--attribute-author
--no-attribute-author

`--attribute-committer`

Attribute cecli commits in the git committer name (default: True). If explicitly set to True, overrides --attribute-co-authored-by precedence for cecli edits. Environment variable: CECLI_ATTRIBUTE_COMMITTER Aliases:

--attribute-committer
--no-attribute-committer

`--attribute-commit-message-author`

Prefix commit messages with 'cecli: ’ if cecli authored the changes (default: False) Default: False Environment variable: CECLI_ATTRIBUTE_COMMIT_MESSAGE_AUTHOR Aliases:

--attribute-commit-message-author
--no-attribute-commit-message-author

`--attribute-commit-message-committer`

Prefix all commit messages with 'cecli: ’ (default: False) Default: False Environment variable: CECLI_ATTRIBUTE_COMMIT_MESSAGE_COMMITTER Aliases:

--attribute-commit-message-committer
--no-attribute-commit-message-committer

`--attribute-co-authored-by`

Attribute cecli edits using the Co-authored-by trailer in the commit message (default: True). If True, this takes precedence over default --attribute-author and --attribute-committer behavior unless they are explicitly set to True. Default: True Environment variable: CECLI_ATTRIBUTE_CO_AUTHORED_BY Aliases:

--attribute-co-authored-by
--no-attribute-co-authored-by

`--git-commit-verify`

Enable/disable git pre-commit hooks with --no-verify (default: False) Default: False Environment variable: CECLI_GIT_COMMIT_VERIFY Aliases:

--git-commit-verify
--no-git-commit-verify

`--commit`

Commit all pending changes with a suitable commit message, then exit Default: False Environment variable: CECLI_COMMIT

`--commit-prompt PROMPT`

Specify a custom prompt for generating commit messages Environment variable: CECLI_COMMIT_PROMPT

`--dry-run`

Perform a dry run without modifying files (default: False) Default: False Environment variable: CECLI_DRY_RUN Aliases:

--dry-run
--no-dry-run

`--skip-sanity-check-repo`

Skip the sanity check for the git repository (default: False) Default: False Environment variable: CECLI_SKIP_SANITY_CHECK_REPO

`--watch-files`

Enable/disable watching files for ai coding comments (default: False) Default: False Environment variable: CECLI_WATCH_FILES Aliases:

--watch-files
--no-watch-files

Fixing and committing:

`--lint`

Lint and fix provided files, or dirty files if none provided Default: False Environment variable: CECLI_LINT

`--lint-cmd`

Specify lint commands to run for different languages, eg: “python: flake8 --select=…” (can be used multiple times) Default: [] Environment variable: CECLI_LINT_CMD

`--auto-lint`

Enable/disable automatic linting after changes (default: True) Default: True Environment variable: CECLI_AUTO_LINT Aliases:

--auto-lint
--no-auto-lint

`--test-cmd VALUE`

Specify command to run tests Default: [] Environment variable: CECLI_TEST_CMD

`--auto-test`

Enable/disable automatic testing after changes (default: False) Default: False Environment variable: CECLI_AUTO_TEST Aliases:

--auto-test
--no-auto-test

`--test`

Run tests, fix problems found and then exit Default: False Environment variable: CECLI_TEST

Upgrading:

`--just-check-update`

Check for updates and return status in the exit code Default: False Environment variable: CECLI_JUST_CHECK_UPDATE

`--check-update`

Check for new cecli versions on launch Default: True Environment variable: CECLI_CHECK_UPDATE Aliases:

--check-update
--no-check-update

`--show-release-notes`

Show release notes on first run of new version (default: None, ask user) Environment variable: CECLI_SHOW_RELEASE_NOTES Aliases:

--show-release-notes
--no-show-release-notes

`--install-main-branch`

Install the latest version from the main branch Default: False Environment variable: CECLI_INSTALL_MAIN_BRANCH

`--upgrade`

Upgrade cecli to the latest version from PyPI Default: False Environment variable: CECLI_UPGRADE Aliases:

--upgrade
--update

`--version`

Show the version number and exit

Modes:

`--message COMMAND`

Specify a single message to send the LLM, process reply then exit (disables chat mode) Environment variable: CECLI_MESSAGE Aliases:

--message COMMAND
--msg COMMAND
-m COMMAND

`--message-file MESSAGE_FILE`

Specify a file containing the message to send the LLM, process reply, then exit (disables chat mode) Environment variable: CECLI_MESSAGE_FILE Aliases:

--message-file MESSAGE_FILE
-f MESSAGE_FILE

`--copy-paste`

Enable automatic copy/paste of chat between cecli and web UI (default: False) Default: False Environment variable: CECLI_COPY_PASTE Aliases:

--copy-paste
--no-copy-paste

`--apply FILE`

Apply the changes from the given file instead of running the chat (debug) Environment variable: CECLI_APPLY

`--apply-clipboard-edits`

Apply clipboard contents as edits using the main model’s editor format Default: False Environment variable: CECLI_APPLY_CLIPBOARD_EDITS

`--exit`

Do all startup activities then exit before accepting user input (debug) Default: False Environment variable: CECLI_EXIT

`--show-repo-map`

Print the repo map and exit (debug) Default: False Environment variable: CECLI_SHOW_REPO_MAP

`--show-prompts`

Print the system prompts and exit (debug) Default: False Environment variable: CECLI_SHOW_PROMPTS

Voice settings:

`--voice-format VOICE_FORMAT`

Audio format for voice recording (default: wav). webm and mp3 require ffmpeg Default: wav Environment variable: CECLI_VOICE_FORMAT

`--voice-language VOICE_LANGUAGE`

Specify the language for voice using ISO 639-1 code (default: auto) Default: en Environment variable: CECLI_VOICE_LANGUAGE

`--voice-input-device VOICE_INPUT_DEVICE`

Specify the input device name for voice recording Environment variable: CECLI_VOICE_INPUT_DEVICE

Other settings:

`--disable-playwright`

Never prompt for or attempt to install Playwright for web scraping (default: False). Default: False Environment variable: CECLI_DISABLE_PLAYWRIGHT

`--file FILE`

specify a file to edit (can be used multiple times) Environment variable: CECLI_FILE

`--read FILE`

specify a read-only file (can be used multiple times) Environment variable: CECLI_READ

`--vim`

Use VI editing mode in the terminal (default: False) Default: False Environment variable: CECLI_VIM

`--chat-language CHAT_LANGUAGE`

Specify the language to use in the chat (default: None, uses system settings) Environment variable: CECLI_CHAT_LANGUAGE

`--commit-language COMMIT_LANGUAGE`

Specify the language to use in the commit message (default: None, user language) Environment variable: CECLI_COMMIT_LANGUAGE

`--yes-always`

Always say yes to every confirmation Environment variable: CECLI_YES_ALWAYS

`--verbose`

Enable verbose output Default: False Environment variable: CECLI_VERBOSE Aliases:

-v
--verbose

`--load LOAD_FILE`

Load and execute /commands from a file on launch Environment variable: CECLI_LOAD

`--encoding VALUE`

Specify the encoding for input and output (default: utf-8) Default: utf-8 Environment variable: CECLI_ENCODING

`--line-endings VALUE`

Line endings to use when writing files (default: platform) Default: platform Environment variable: CECLI_LINE_ENDINGS

`--config CONFIG_FILE`

Specify the config file (default: search for .cecli.conf.yml in git root, cwd or home directory) Aliases:

-c CONFIG_FILE
--config CONFIG_FILE

`--env-file ENV_FILE`

Specify the .env file to load (default: .env in git root) Default: .env Environment variable: CECLI_ENV_FILE

`--suggest-shell-commands`

Enable/disable suggesting shell commands (default: True) Default: True Environment variable: CECLI_SUGGEST_SHELL_COMMANDS Aliases:

--suggest-shell-commands
--no-suggest-shell-commands

`--fancy-input`

Enable/disable fancy input with history and completion (default: True) Default: True Environment variable: CECLI_FANCY_INPUT Aliases:

--fancy-input
--no-fancy-input

`--multiline`

Enable/disable multi-line input mode with Meta-Enter to submit (default: False) Default: False Environment variable: CECLI_MULTILINE Aliases:

--multiline
--no-multiline

`--notifications`

Enable/disable terminal bell notifications when LLM responses are ready (default: False) Default: False Environment variable: CECLI_NOTIFICATIONS Aliases:

--notifications
--no-notifications

`--notifications-command COMMAND`

Specify a command to run for notifications instead of the terminal bell. If not specified, a default command for your OS may be used. Environment variable: CECLI_NOTIFICATIONS_COMMAND

`--detect-urls`

Enable/disable detection and offering to add URLs to chat (default: True) Default: True Environment variable: CECLI_DETECT_URLS Aliases:

--detect-urls
--no-detect-urls

`--editor VALUE`

Specify which editor to use for the /editor command Environment variable: CECLI_EDITOR

`--shell-completions SHELL`

Print shell completion script for the specified SHELL and exit. Supported shells: bash, tcsh, zsh. Example: cecli --shell-completions bash Environment variable: CECLI_SHELL_COMPLETIONS

Last updated: