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

# moorcheh upload-file

> Upload one file from ~/.moorcheh/uploads into a text namespace.

## Overview

Copies nothing — the file must already exist under `~/.moorcheh/uploads`. The CLI maps the host path to `/uploads/...` and calls `POST /namespaces/{namespace_name}/files`.

Poll progress with [moorcheh file-job-status](/on-prem/cli/files/file-job-status).

## Synopsis

```bash theme={null}
moorcheh upload-file --namespace-name NAME --file PATH \
  [--force-reindex] [--metadata-json JSON] [--base-url URL]
```

## Options

| Flag               | Required | Description                                     |
| ------------------ | -------- | ----------------------------------------------- |
| `--namespace-name` | Yes      | Target text namespace                           |
| `--file`           | Yes      | Host path to a file under `~/.moorcheh/uploads` |
| `--force-reindex`  | No       | Replace index even if size/mtime unchanged      |
| `--metadata-json`  | No       | JSON object merged into chunk metadata          |
| `--base-url`       | No       | Default `http://localhost:8080`                 |

## Examples

```bash theme={null}
# Copy a file into the upload dir first
copy C:\Users\you\Documents\document.pdf %USERPROFILE%\.moorcheh\uploads\

moorcheh upload-file --namespace-name my-documents --file "%USERPROFILE%\.moorcheh\uploads\document.pdf"

moorcheh file-job-status --namespace-name my-documents --job-id <job_id>
```

```bash theme={null}
moorcheh upload-file --namespace-name my-documents \
  --file ~/.moorcheh/uploads/document.pdf \
  --force-reindex \
  --metadata-json '{"department":"engineering"}'
```

## Batch upload from JSON

Use `moorcheh upload-files` with a JSON file whose `files[].path` values are **container paths** (`/uploads/...`). See [API: Upload file](/on-prem/api-references/files/upload).

## Related

* [moorcheh list-files](/on-prem/cli/files/list-files)
* [moorcheh delete-file](/on-prem/cli/files/delete-file)
* [API: Upload file](/on-prem/api-references/files/upload)