feat(cli): add --ephemeral CLI argument to prevent config.json updates

[kiloconnect]

Summary

Implements ephemeral mode as a CLI argument (--ephemeral) to complement the existing KILO_EPHEMERAL_MODE environment variable. This helps prevent accidentally injecting org IDs or other settings into config.json during testing/development and prevents race conditions when running multiple CLI instances in parallel.

Fixes

Closes #4541

Changes

Core Implementation

• ✅ Add --ephemeral / -e CLI flag to index.ts
• ✅ Add ephemeral field to CLIOptions type
• ✅ Implement setEphemeralMode() function in env-config.ts
• ✅ Update isEphemeralMode() to check both CLI flag and env var
• ✅ CLI flag takes precedence over environment variable

Testing

• ✅ Add comprehensive tests for ephemeral mode functionality in ephemeral-mode.test.ts
• Tests cover CLI flag, env var, and precedence scenarios

Documentation

• ✅ Update CLI documentation with:
  • Ephemeral mode section with usage examples
  • Use cases (parallel testing, CI/CD, development)
  • Behavior description
  • Environment variable reference update

Usage Examples

Basic Usage

# Run with ephemeral mode enabled
kilocode --ephemeral "implement feature X"

# Works with other flags
kilocode --ephemeral --auto "run tests"
kilocode --ephemeral --parallel "improve performance"

Parallel Testing (Prevents Race Conditions)

# Run multiple instances without config conflicts
kilocode --ephemeral --auto "test feature A" &
kilocode --ephemeral --auto "test feature B" &
kilocode --ephemeral --auto "test feature C" &
wait

CI/CD Integration

# Use environment variables without persisting them
export KILO_PROVIDER_TYPE=anthropic
export KILO_API_KEY=$ANTHROPIC_API_KEY
export KILO_API_MODEL_ID=claude-3-5-sonnet-20241022
kilocode --ephemeral --auto "run integration tests"

Behavior

When ephemeral mode is enabled:

• Configuration is loaded from config.json (if it exists) or environment variables
• All configuration changes are kept in memory only
• No writes are made to config.json during the session
• Provider/model overrides from CLI arguments are not persisted
• Auto-approval settings changes are not saved

Testing

Run the new tests:

cd cli && pnpm test src/config/__tests__/ephemeral-mode.test.ts

Related

This PR addresses the race condition issue described in #4541 by providing a CLI-based way to enable ephemeral mode, making it easier to run multiple CLI instances in parallel without config file conflicts.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 787d821

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[kiloconnect]

✅ No Issues Found

5 files reviewed | Confidence: 92% | Recommendation: Merge

Review Details

Files:

• apps/kilocode-docs/docs/cli.md - Documentation for ephemeral mode
• cli/src/config/__tests__/ephemeral-mode.test.ts - Comprehensive test coverage
• cli/src/config/env-config.ts - Core implementation
• cli/src/index.ts - CLI entry point integration
• cli/src/types/cli.ts - Type definition

Checked: Security, bugs, logic errors, type safety, test coverage

Implementation Quality:

• ✅ Clean implementation following existing codebase patterns
• ✅ CLI flag properly takes precedence over environment variable
• ✅ Backward compatible with existing KILO_EPHEMERAL_MODE env var behavior
• ✅ Comprehensive test coverage for CLI flag, env var, and precedence scenarios
• ✅ Well-documented with usage examples and use cases
• ✅ Proper integration with persistence.ts to prevent config writes

Notes:

• The ephemeral option is passed to CLI constructor but not directly used within the class - this is fine as the behavior is controlled via the global setEphemeralMode() call earlier in the flow
• The existing behavior where ephemeral mode is implicitly enabled when env config exists (unless KILO_EPHEMERAL_MODE=false) is preserved, maintaining backward compatibility