# Get started

## Folders

All service files live in the `.raw2md` folder in your home directory:

```text
~/.raw2md/
  settings.json     # models and settings; created by raw2md init
  prompts.yaml      # prompts of the LLM stages; created by raw2md init
  keywords.yaml     # words that the cleaning rules look for; created by raw2md init
  models/           # weights of raw2md-engine; downloaded by raw2md init
  state/            # queue, lock, daily request counter
  logs/raw2md.log   # log of the last run
  tmp/              # temporary conversion files
```

The weights take about 3.3 GB. `raw2md init` downloads them from the [raw2md-models](https://huggingface.co/MikeDolg/raw2md-models) repository on Hugging Face. Without `init`, the first PDF or DjVu conversion downloads the missing files. When all the weights are in place, the tool makes no network request for them.

## Quick start

Give raw2md a file, a folder, or nothing at all:

```bash
raw2md book.pdf   # a single file
raw2md scans      # every pdf, djvu, docx, and md file in the folder, without subfolders
raw2md            # the current folder
```

Each result lands next to its source:

```text
book.pdf   # source
book.md    # result
book/      # images, if the document has any

notes.md            # Markdown source
notes_cleaned.md    # result; the source stays untouched
```

Every result starts with a header. The `status` field holds the verdict of the quality evaluation, and `issues` lists the checks that fired:

```yaml
---
raw2md_version: 0.1.0
source: book.pdf
engine: raw2md-engine
inspection: none
post: none
converted_at: 2026-10-03
source_hash: 9rZ2...
status: ok
issues:
- headings
---
```

## Options

These are the flags you will reach for most often:

| Flag | What it does |
|---|---|
| `-o DIR` | puts the results into `DIR` instead of next to the source |
| `-e <model>` | recognizes PDF and DjVu with a model instead of `raw2md-engine` |
| `-i <model>` | turns on inspection, which checks the text against the source |
| `-p <model>` | turns on post-processing |
| `-s` | keeps a finished result and does not convert the file again |
| `-d` | saves the text after each stage into the `<name>.debug` folder |
| `-h` | prints the list of all flags |
| `--disable-image-extraction` | skips the images but keeps their captions |

The model in `-e`, `-i`, and `-p` is a key from `settings.json`, such as `gemini_api`. The [reference](/docs/reference/) covers every flag, along with the `resume`, `init`, `settings`, `prompts`, and `keywords` commands.

## Settings

Without a settings file, raw2md falls back on its built-in settings, which know two models:

| Key | Model | Stages | What you need |
|---|---|---|---|
| `gemini_api` | Gemini through the API | `-e`, `-i`, `-p` | an API key in the `GOOGLE_API_KEY` variable |
| `claude_cli` | Claude Code through `claude -p` | `-p` | `claude` installed, signed in, and on `PATH` |

To turn on the LLM stages, put your key into `GOOGLE_API_KEY` and name the model in the flag:

```bash
raw2md book.pdf -i gemini_api -p gemini_api
```

The built-in `gemini_api` model and its limits, 15 requests per minute and 500 per day, target the free tier of Google AI Studio, so a free API key is enough to start. Google sets the actual quotas for each project and can change them. With a paid key, you can pick a larger model and raise the limits.

To change a model or its limits, create the settings file and open it:

```bash
raw2md init
raw2md settings edit
```

These are the fields you are most likely to change:

| Field | What it sets |
|---|---|
| `models.<key>.model` | the model name at the provider |
| `models.<key>.rpm`, `rpd` | the request limits per minute and per day |
| `models.<key>.pages_per_request` | how many source pages go into one request |
| `raw2md-engine.recognition_batch_size` | the batch size of the engine recognition; a smaller number uses less video memory |

The [reference](/docs/reference/#service-files) describes every field, as well as `prompts.yaml` and `keywords.yaml`.