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

# veloiq search: Register Models for Global Search

> The veloiq search command registers models and fields for VeloIQ's header search bar — writes config/search.json read by the backend.

`veloiq search` manages which models and fields appear in VeloIQ's built-in header search bar. Each subcommand reads and writes `config/search.json` at your project root. The backend serves this file at `GET /config/search`, and the React frontend reads it on startup to build the search index. You do not need to edit `search.json` by hand — use `veloiq search` to keep it consistent.

## Subcommands

### `veloiq search add-model`

Registers a model in the search index. Optionally adds specific fields in the same command with `--fields`.

```bash theme={null}
veloiq search add-model <ModelName> [--fields field1,field2,...]
```

**Examples:**

```bash theme={null}
veloiq search add-model Task
veloiq search add-model Task --fields title,description
veloiq search add-model TeamMember --fields name,email
```

If you do not pass `--fields` and no global fields are configured yet, the backend searches all string fields of the model by default until you add specific fields.

### `veloiq search add-field`

Adds a field to the global list of searchable attributes. The field name is searched across **all** registered models, not just one.

```bash theme={null}
veloiq search add-field <fieldname>
```

**Examples:**

```bash theme={null}
veloiq search add-field title
veloiq search add-field description
veloiq search add-field name
```

### `veloiq search remove-model`

Deregisters a model from the search index. The model's data will no longer appear in search results.

```bash theme={null}
veloiq search remove-model <ModelName>
```

**Example:**

```bash theme={null}
veloiq search remove-model Task
```

### `veloiq search remove-field`

Removes a field from the global searchable attributes list.

```bash theme={null}
veloiq search remove-field <fieldname>
```

### `veloiq search list`

Prints the current search configuration — registered models, configured fields, and the path to `search.json`.

```bash theme={null}
veloiq search list
```

## The `config/search.json` structure

After running a sequence of `add-model` and `add-field` commands:

```bash theme={null}
veloiq search add-model Task --fields title,description
veloiq search add-model Project --fields name,description
```

The resulting `config/search.json` looks like this:

```json theme={null}
{
  "models": [
    "Task",
    "Project"
  ],
  "fields": [
    "title",
    "description",
    "name"
  ]
}
```

* **`models`** — the list of SQLModel class names to include in search results.
* **`fields`** — the list of field names searched across every model in `models`. Fields are deduplicated automatically; adding the same field twice has no effect.

## Field matching rules

A field in `fields` matches a model attribute if the attribute name **exactly equals** the field name, or if the attribute name **ends with** `_<fieldname>`. For example, a field entry of `name` matches both `name` and `full_name` on any registered model. This lets you configure one generic field key to match common naming variations across different models.

## How the backend and frontend use this file

The backend reads `config/search.json` at startup and exposes it at:

```
GET /config/search
```

The React frontend fetches this endpoint when the application loads and uses the returned model and field lists to build the header search bar queries. Any changes you make with `veloiq search` take effect on the next server restart.

<Note>
  `veloiq search` auto-detects the project root by walking up from your current directory looking for `backend/app/modules/`. Run it from anywhere inside your project.
</Note>

<Tip>
  Start with `veloiq search add-model <Name> --fields field1,field2` to register a model and its fields in one step, then use `veloiq search list` to verify the result before restarting the server.
</Tip>