CLI Commands & Flags

Quick Start

caretforge                        # interactive chat (default)
caretforge "fix the login bug"    # one-shot task

CaretForge follows the same invocation pattern as Claude Code:

• No arguments → interactive REPL
• Task as argument → one-shot execution

Global Flags

These flags work with any command:

Flag	Description	Default
-V, --version	Print version number	—
--provider <name>	Provider to use	from config
--model <id>	Model deployment ID	from config
--stream	Enable streaming output	true
--no-stream	Disable streaming output	—
--json	Emit structured JSON output	false
--trace	Enable verbose debug logging	false
--allow-shell	Auto-approve shell execution	false
--allow-write	Auto-approve file writes	false
-h, --help	Display help	—

Permissions

By default, the agent prompts you before writing files or running commands:

  ⚡ Write to src/utils.ts
  Allow? [y]es / [n]o / [a]lways

Response	Effect
y	Allow this one time
n	Deny — the agent will adapt
a	Allow all future calls of this type (session)

Use --allow-write and --allow-shell to skip prompts entirely.

Commands

caretforge (default)

Start an interactive chat session. This is the default when no command is given.

caretforge
caretforge --model claude-opus-4-6
caretforge --provider azure-foundry --allow-write

Slash commands available inside the REPL:

Command	Description
/help	Show available commands
/model	List models from all configured providers
/model <id>	Switch model mid-conversation
/clear	Clear conversation history
/compact	Trim older messages from history
/exit	Exit CaretForge
/quit	Exit CaretForge (alias)

You can also type exit, quit, or q without the slash to leave the REPL.

TIP

The /model command (without arguments) in the REPL lists models from all configured providers, grouped by provider name. This differs from caretforge model list on the command line, which shows only the active provider's models.

File context with @:

Reference files directly in your prompts using the @ prefix. Press Tab after @ to autocomplete file paths from your working directory.

> Explain @src/core/agent.ts
> Compare @package.json with @tsconfig.json

Files are indexed on startup (up to 5,000 files, depth 4) with a comprehensive governance model. On startup you'll see indexing statistics:

  Indexed 142 files (git) · skipped 3 binary, 1 large, 0 ignored

During interactive @ browsing, file sizes are displayed next to each file name. See the Security page for full details on file indexing governance.

caretforge "task" / caretforge run [task...]

Execute a task non-interactively.

# Shorthand (no subcommand needed)
caretforge "Explain this error: ENOENT"

# Explicit run command
caretforge run "Refactor the auth module"

# From stdin
echo "Fix the bug" | caretforge run

# With JSON output for piping
caretforge run "Count lines in src/" --json

JSON output format:

{
  "task": "the task description",
  "model": "claude-opus-4-6",
  "provider": "azure-anthropic",
  "finalContent": "The agent's response...",
  "toolCallCount": 2,
  "durationMs": 4521,
  "messages": [...]
}

caretforge chat

Explicitly start interactive chat (same as running caretforge with no arguments).

caretforge chat
caretforge chat --model gpt-4.1

caretforge model list

List models configured for the active provider.

caretforge model list
caretforge model list --json
caretforge model list --provider azure-anthropic

caretforge config init

Create a starter configuration file.

caretforge config init
caretforge config init --with-secrets

Option	Description
--with-secrets	Include placeholder API key in the file

caretforge config show

Display the current configuration with secrets redacted.

caretforge config show
caretforge config show --json

caretforge doctor

Validate your configuration and diagnose common issues.

caretforge doctor

Checks: Node.js version, config file validity, endpoint configuration, API key presence, model setup. Exit code 1 if any check fails.

Examples

# Interactive with Claude on Azure
caretforge --model claude-opus-4-6

# One-shot task with full autonomy
caretforge "Refactor the database layer" --allow-write --allow-shell

# Debug mode — see API calls and tool execution
caretforge "Read README.md" --trace

# JSON output for scripting
caretforge "List all exports in src/index.ts" --json | jq .finalContent

# Switch provider on the fly
caretforge "Hello" --provider azure-foundry --model gpt-4.1