---
title: "tractorbeam query"
description: "The Tractorbeam API's query operations."
sidebar:
  label: "query"
  order: 27
---

```sh
tractorbeam query <subcommand> [flags]
```

## Shared flags

Every subcommand takes these flags.

| Flag | Description |
| --- | --- |
| `--config <string>` | The Project's `tractorbeam.config.ts`. Defaults to the one in the current directory or its nearest ancestor. |
| `--workspace <string>` | Workspace name. Environment variable: `TRACTORBEAM_WORKSPACE`. |
| `--origin <string>` | The Tractorbeam origin to call instead of the default, such as a proxy's. Environment variable: `TRACTORBEAM_ORIGIN`. |
| `--token <string>` | Access token. Defaults to the saved interactive session. Environment variable: `TRACTORBEAM_TOKEN`. |

## `query list`

Returns the Queries the Branch's HEAD, or a retained Commit on it, selects, each with its input's and output's schemas. Needs Workspace authority; an App token can't list Queries.

```sh
tractorbeam query list [flags]
```

| Flag | Description |
| --- | --- |
| `--at-commit-id <string>` | The ID of a retained Commit on the Branch to read at. Defaults to the Branch's HEAD. |
| `--branch <string>` | Branch name. Defaults to the Branch you last switched to, or main. Environment variable: `TRACTORBEAM_BRANCH`. |

## `query get`

Returns the Query with this name selected by the Branch's HEAD or by a retained Commit on it, with its input's and output's schemas. Returns 404 when none is selected. Needs Workspace authority; an App token can't retrieve Queries.

```sh
tractorbeam query get [flags] <query>
```

| Argument | Description |
| --- | --- |
| `<query>` | The name of the Query to retrieve. |

| Flag | Description |
| --- | --- |
| `--at-commit-id <string>` | The ID of a retained Commit on the Branch to read at. Defaults to the Branch's HEAD. |
| `--branch <string>` | Branch name. Defaults to the Branch you last switched to, or main. Environment variable: `TRACTORBEAM_BRANCH`. |

## `query invoke`

Runs the named Query at one Commit and returns what its code returned. The read is at the Branch's HEAD, at a retained Commit `atCommitId` names, or at a HEAD including `minimumCommitId`. Needs `queries:invoke`. An App token can invoke the Queries its App selects.

```sh
tractorbeam query invoke [flags] <query>
```

| Argument | Description |
| --- | --- |
| `<query>` | The name of the Query to invoke. |

| Flag | Description |
| --- | --- |
| `--branch <string>` | Branch name. Defaults to the Branch you last switched to, or main. Environment variable: `TRACTORBEAM_BRANCH`. |
| `--json <json>` | The request's body as JSON. |
