# uip context-grounding

> Syntax and options for `uip context-grounding`, a bridge to the Python UiPath CLI for context grounding operations.

`uip context-grounding` is a thin bridge to the Python-based UiPath SDK's context grounding operations. It detects a suitable Python interpreter, confirms the `uipath` Python package is installed, and forwards everything else to the Python CLI as `uipath context-grounding <args>` — this tool defines no native subcommands of its own beyond `setup`.

Unlike [`uip codedagent`](./uip-codedagent.md), which only forwards a fixed whitelist of subcommand names, `context-grounding-tool` forwards **any** unrecognized command — there is no allowlist to consult before a new Python-side verb works here.

See [Tools (plugins)](./concepts-tools.md) for how thin wrappers differ from full tools.

## Synopsis

```
uip context-grounding setup [--force]
uip context-grounding <any-command> [args...]
uip context-grounding help
uip context-grounding
```

`setup` and any forwarded command honor the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md).

## uip context-grounding setup

Detect Python and verify the `uipath` package is installed. Results are cached in a per-user file so subsequent `context-grounding` commands can resolve the Python binary instantly.

### Arguments

None.

### Options

- `--force` — Re-run detection even if a cached result is present.

### Examples

```bash
uip context-grounding setup
uip context-grounding setup --force
```

### Data shape (`--output json`)

```json
{
  "Code": "ContextGroundingSetup",
  "Data": {
    "PythonPath": "/usr/bin/python3.11",
    "Package": "uipath",
    "PackageInstalled": "Yes",
    "PackageVersion": "1.0.0"
  }
}
```

### Environment checks

- Allowed Python versions are configured via the environment variable `PYTHON_TOOL_PYTHON_VERSIONS`. An empty list raises `Failure` at setup time.
- If a `.venv` directory exists in the current working directory but no virtual environment is activated, setup refuses to run and suggests activating it first (`.venv\Scripts\activate` on Windows, `source .venv/bin/activate` elsewhere).

## Forwarded commands

Any subcommand that isn't `setup` or `help` is forwarded to the Python `uipath` CLI as `uipath context-grounding <args>` — there is no fixed whitelist to check against; a brand-new verb the Python package adds tomorrow works here today, with one exception:

:::note
**`auth` is blocked.** Calling `uip context-grounding auth ...` fails immediately with `Result: ValidationError` (exit code `3`) and the message *"Use 'uip login' for authentication."* — **unless** you pass `--force`, which bypasses this one filter and lets the `auth` call through to Python. This is the opposite of `--force`'s effect on `uip codedagent`, where `--force` is always silently stripped and never reaches Python — here it's a real, if narrow, escape hatch.
:::

### Examples

```bash
# Hand off to the Python CLI's index command
uip context-grounding index ./my-index

# Search a context grounding index
uip context-grounding search "invoice total" --index my-index

# Blocked without --force
uip context-grounding auth login
# Result: ValidationError — "Use 'uip login' for authentication."

# Bypasses the auth filter
uip context-grounding auth login --force
```

:::note
Because forwarded commands are defined by the `uipath` Python package, their flags and output shape are whatever that package emits — not the CLI's standard `Code`/`Data` envelope. Treat the CLI here as a transport. For the argument surface, run `uip context-grounding <command> --help`.
:::

**Output-format relay**: when the global `--output` is `json`, the CLI appends `--format json` to the forwarded command automatically (skipped for `--help` calls, or when the forwarded args already contain `--format`) — the Python CLI must support `--format json` for this to have any effect; no other output format is relayed this way.

**Bare invocation and `help` both forward** — unlike `uip codedagent` (where bare `help` shows Commander's own help), `uip context-grounding` with no arguments forwards to `exec --help`, and `uip context-grounding help` explicitly forwards to the same `exec --help` call. Both surface the Python package's own help text, not this tool's.

**Auth relay**: before forwarding, the CLI reads the session created by [`uip login`](./uip-login.md) and injects it into the Python subprocess's environment, the same mechanism [`uip codedagent`](./uip-codedagent.md#forwarded-commands) uses. If you are not logged in, forwarding still works; the Python CLI runs without those variables.

## Exit codes

Standard [exit codes](./exit-codes.md) apply, plus `3` specifically for the blocked `auth` command described above. The forwarded subprocess's exit code is otherwise relayed directly to the parent shell.

## Related

- [Tools (plugins)](./concepts-tools.md) — thin-wrapper tool model.
- [`uip codedagent`](./uip-codedagent.md) — the same Python-bridge pattern, with a fixed forwarding whitelist instead of forwarding everything.
- [`uip login`](./uip-login.md) — creates the session that is relayed to the Python runtime.
- [`uip tools`](./uip-tools.md) — install, update, uninstall the `context-grounding-tool` package itself.