> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taho.is/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Flag Reference

> Complete reference for all TAHO Lift command-line flags and options.

Every flag you can pass to `lift`. When no flags are given, Lift runs the pipeline tools specified in your config file (or all tools by default) in passive mode on the latest commit.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lift [flags]
```

## Processing modes

These flags control *whether* Lift processes a commit, not *which tools* run.

| Flag | Long       | Description                                                                     |
| ---- | ---------- | ------------------------------------------------------------------------------- |
|      | *(none)*   | **Passive mode** (default). Exits silently if the commit was already processed. |
| `-f` | `--force`  | Force re-processing even if the commit was already processed. No prompt.        |
| `-p` | `--prompt` | Prompt before re-processing an already-processed commit.                        |

Passive mode is the default so you can run `lift` as often as you like — in a hook, an alias, or muscle memory — without duplicating work.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Re-process a commit that Lift already handled
lift -f

# Ask first, then re-process if you confirm
lift -p
```

## Tool selection

When no tool flag is given, Lift runs the tools from the `pipeline` config setting (default: all four tools). When you pass one or more tool flags, *only* those tools run, overriding the config.

| Flag | Long        | Description                           |
| ---- | ----------- | ------------------------------------- |
| `-m` | `--message` | Run Inky (commit message improvement) |
| `-d` | `--doc`     | Run Doc (documentation updates)       |

Tool flags combine freely:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Run only Inky
lift -m

# Run Inky and Doc
lift -m -d

```

## Task number

| Flag | Long         | Description                                                            |
| ---- | ------------ | ---------------------------------------------------------------------- |
| `-t` | `--task NUM` | Prepend a task number prefix to the commit message (e.g., `TAHO-123:`) |

The prefix defaults to `TAHO` and can be overridden via the `inky.task_prefix` config setting.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Prepend TAHO-123: to the commit message
lift -t 123
```

## Pull request

| Flag | Long   | Description                                                            |
| ---- | ------ | ---------------------------------------------------------------------- |
|      | `--pr` | Prompt to create or update a pull request after the pipeline completes |

After all tools finish, Lift asks whether you'd like to open or update a PR. Stack mode enables this automatically.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Run the pipeline, then prompt for a PR
lift --pr

```

## Cleanup mode

| Flag | Long        | Description                                                                 |
| ---- | ----------- | --------------------------------------------------------------------------- |
| `-c` | `--cleanup` | Revert `.md` file changes and replace the commit message with a placeholder |

<Warning>
  Cleanup mode is destructive. It reverts all Markdown file changes from the current commit and replaces the commit message with a placeholder.
</Warning>

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Undo Lift's changes on this commit
lift -c
```

## Output control

| Flag | Long      | Description                                      |
| ---- | --------- | ------------------------------------------------ |
| `-q` | `--quiet` | Suppress progress indicators and minimize output |

Useful for scripting or CI environments where animated spinners aren't wanted.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Run silently
lift -q
```

## Common combinations

| Command      | What it does                             |
| ------------ | ---------------------------------------- |
| `lift`       | Full pipeline, passive mode              |
| `lift -f`    | Full pipeline, force re-processing       |
| `lift -m`    | Inky only                                |
| `lift -d -f` | Force re-run Doc only                    |
| `lift -s`    | Stack mode (all commits, then PR prompt) |
| `lift -c`    | Cleanup (revert docs and commit message) |

## Configuration

| Flag | Long                 | Description                                                      |
| ---- | -------------------- | ---------------------------------------------------------------- |
|      | `--config`           | Display the resolved configuration reference and exit            |
|      | `--script-dir DIR`   | Override the script directory (overrides config)                 |
|      | `--external-scripts` | Use legacy bash scripts instead of internal Rust implementations |

Run `lift --config` to see all available configuration options and the resolved merge result.

## Preconditions

Lift validates two things before it runs:

1. **Clean working directory** — uncommitted changes cause Lift to exit with an error. Commit or stash your work first.
2. **Not on the main branch** — Lift refuses to run on the configured main branch (default: `main`). Switch to a feature branch first.