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

```sh
tractorbeam function <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`. |

## `function invoke`

Takes one call of any kind, as `\{ "query": \{ "name", ... \} \}`, `\{ "mutation": \{ "name", ... \} \}`, or `\{ "action": \{ "name", ... \} \}`, runs it exactly as the kind's own operation does, `POST /api/v1/queries/\{query\}/invoke`, `POST /api/v1/mutations/\{mutation\}/invoke`, or `POST /api/v1/actions/\{action\}/invoke`, and returns the same reply, tagged by the same kind. An Action call requires an `idempotency-key`, and a Mutation call takes one: a retry with the same key and request returns the first call's result, and one with another request returns 422. Instead of a Query's name, a Query call can include its code, `\{ "query": \{ "code", ... \} \}`. The code runs once as a Query at one Commit. It reads every Table and Object type except those requiring a Marking, each document and Object as the caller can read it. If its code throws, the call returns 400 with the error's message. An MCP Server's token can make such a call; another App's token can't. An Action call can include its code too, `\{ "action": \{ "code", ... \} \}`. Such a call creates an Action Invocation running the code once. The Invocation can call every Query and Mutation on the Branch as the caller would. It reads the Secrets and Connectors it names and reaches the origins it names. Such a call needs `actions:invoke` and `actions:write`, and `egress:manage` when it names Connectors or origins. Only an MCP Server's token whose definition allows inline Actions can make it.

```sh
tractorbeam function invoke [flags]
```

| 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. |
