# CLI commands

Operate Vision from a terminal, select the existing Vault, and run product operations with JSON.

The installed package provides `indra` and, in versions with the alias, `zortex`. Check `indra --version` and `indra --help` before using commands from a newer handbook.

## Select the existing Vault

`indra` requires an absolute Vault path for ordinary runtime operations:

```sh
indra --root "/absolute/path/to/your/Vault" status
```

`zortex` resolves an explicit `--root` first, then `ZORTEX_ROOT`, then its installation's saved Codex binding. New installations use a platform default. An invalid saved binding needs correction; it should not silently select another collection.

| Platform | Default for a new installation |
| --- | --- |
| Windows | `%LOCALAPPDATA%\Zortex\Indra` |
| macOS and Unix | `~/.zortex/indra-v2` |

Expand these to an absolute path when using `--root`. Keep your existing choice when upgrading. Do not create another Vault to work around a connection error.

An older installation may own a different global `zortex` executable. Check the command's resolved path if its help does not match this guide. Do not force-overwrite another installation's command.

Some longer examples use `$indra_root` to keep the same Vault across commands. Set it to your existing absolute path in the terminal where you will run the example:

```sh
# macOS, Linux, or another POSIX shell
indra_root='/absolute/path/to/your/Vault'
```

```powershell
# PowerShell
$indra_root = 'C:/absolute/path/to/your/Vault'
```

Replace the example path. Then `indra --root "$indra_root" status` should show the Vault you already use.

## Open and inspect

| Command | Purpose |
| --- | --- |
| `indra --version` | Print the installed package version. |
| `indra --help` | Print command usage. |
| `indra --root <Vault> help` | Open Local connection help and keep it available. |
| `indra --root <Vault> help --no-open` | Print the live help link without opening a browser. |
| `indra web --root <Vault>` | Open the local Galaxy app. |
| `indra --root <Vault> status` | Inspect source and runtime state. |
| `indra --root <Vault> plugins` | List installed components. |
| `indra --root <Vault> vault` | Inspect Vault identity and retained source counts. |
| `indra --root <Vault> instruction` | Read installed operating guidance. |
| `indra --root <Vault> handbook` | Read the product handbook and available freshness metadata. |

Quote a Vault path containing spaces. `zortex help` opens the connection page; `zortex --help` prints usage. Keep long-running web and help commands alive while using their pages.

## Connect and collect

```sh
indra --root "/absolute/path/to/your/Vault" onboard
indra --root "/absolute/path/to/your/Vault" connect --source gmail --presentation open
indra --root "/absolute/path/to/your/Vault" recover
```

`onboard` starts or resumes automatic setup. `connect` targets one source; `--presentation open` opens the authorization page for you to complete. Without that option, automatic setup may return a continuation for an agent. `recover` opens assistance without another automatic pass. Finish or cancel a pending authorization before starting another for the same source.

For a supported explicit collection:

```sh
indra --root "/absolute/path/to/your/Vault" sync --source gmail --request-id gmail-import-1
```

Always name the intended source; omitting `--source` defaults to `chrome-history`. Review [Sync your sources](/docs/vision/connectors/sync) for partial runs and automatic-sync controls.

## Run an operation with JSON

There is no `call` subcommand. Use the operation name, followed by `--json` and one JSON object:

```sh
indra --root "/absolute/path/to/your/Vault" actions --json '{"source":"browser-use"}'
indra --root "/absolute/path/to/your/Vault" manage --json '{"what":"onboarding"}'
indra --root "/absolute/path/to/your/Vault" action --json '{"name":"connector.read","params":{"source":"gmail","request":{"limit":5}}}'
```

The single quotes belong to the shell; JSON property names and text values use double quotes. These examples work in shells that preserve a single-quoted argument. When writing a Windows path inside JSON, escape each backslash or use a supported forward-slash path.

`actions` without JSON returns the fixed shared Action names. Provider discovery uses `actions` with `source`, then `source` and `method`. Execution uses `action`; its argument object is the same one passed to the MCP tool `indra.action`.

## Search collected information

```sh
indra --root "/absolute/path/to/your/Vault" search --sql 'SELECT source, COUNT(*) AS records FROM z_records GROUP BY source ORDER BY source'
indra --root "/absolute/path/to/your/Vault" search --json '{"sql":"SELECT id,source,source_id,title FROM z_records WHERE title LIKE ? LIMIT 10","params":["%launch%"]}'
```

`sql` is an alias for `search`. The command accepts SQL, not a natural-language search prompt. See [SQL reference](/docs/vision/reference/sql).

## Manage the background host

Use `host start`, `host stop`, `host status`, `host enable`, and `host disable` after the same root argument. Start/stop controls the running host; enable/disable controls login startup. Neither erases data.

Remote access uses `host local-cloud`; see its [complete setup and shutdown procedure](/docs/vision/reference/remote-access).

## Read errors

Unknown arguments and missing roots are command errors. A returned `err` describes an operation failure. Read its code and message; use [Troubleshooting](/docs/vision/settings/troubleshooting) to distinguish authentication, missing configuration, query limits, and runtime availability.

After a write loses its response, inspect the target before repeating it. After a connection returns a job, follow that job rather than treating the command's return as completion.
