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

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

## `action list`

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

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

## `action get`

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

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

| Argument | Description |
| --- | --- |
| `<action>` | The name of the Action 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`. |

## `action invoke`

Creates an Action Invocation of the Action at the Branch's HEAD, with the request's input and, for a bound Action, its target Object, and returns the Invocation. A request with the same `idempotency-key` and request returns the same Invocation; one with another request returns 422. An Action listing a Secret without a value fails at once. Needs `actions:invoke`. An App token can invoke the Actions its App selects.

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

| Argument | Description |
| --- | --- |
| `<action>` | The name of the Action to invoke. |

| Flag | Description |
| --- | --- |
| `--branch <string>` | Branch name. Defaults to the Branch you last switched to, or main. Environment variable: `TRACTORBEAM_BRANCH`. |
| `--target <string>` | The ID of a bound Action's Object. |
| `--input <json>` | The Action's input, in its declared type's JSON form. |
| `--json <json>` | The body's fields as one JSON object. Flags given as well override its fields. |

## `action list-invocations`

Returns a page of every principal's Invocations of one Action on the Branch, newest first. Needs `actions:read` and Workspace authority; an App token can't list Invocations.

```sh
tractorbeam action list-invocations [flags]
```

| Flag | Description |
| --- | --- |
| `--limit <string>` | The most items the page returns, from 1 to 200. Defaults to 50. |
| `--cursor <string>` | A cursor for use in pagination: the `nextCursor` of the previous page, whose read the page continues. |
| `--action <string>` | The name of the Action whose Invocations to list. |
| `--branch <string>` | Branch name. Defaults to the Branch you last switched to, or main. Environment variable: `TRACTORBEAM_BRANCH`. |
| `--all` | Read every page, following `nextCursor`, and print all their items together. |

## `action get-invocation`

Retrieves an Action Invocation the caller can see, with its result once it succeeded. Needs `actions:read`.

```sh
tractorbeam action get-invocation [flags] <action-invocation>
```

| Argument | Description |
| --- | --- |
| `<action-invocation>` | The ID of the Invocation to retrieve. |

| Flag | Description |
| --- | --- |
| `--branch <string>` | Branch name. Defaults to the Branch you last switched to, or main. Environment variable: `TRACTORBEAM_BRANCH`. |

## `action cancel-invocation`

Cancels an Action Invocation the caller can see and returns it. A canceled Invocation doesn't start another attempt. Canceling an Invocation after it has ended returns it unchanged. Needs `actions:invoke`.

```sh
tractorbeam action cancel-invocation [flags] <action-invocation>
```

| Argument | Description |
| --- | --- |
| `<action-invocation>` | The ID of the Invocation to cancel. |

| Flag | Description |
| --- | --- |
| `--branch <string>` | Branch name. Defaults to the Branch you last switched to, or main. Environment variable: `TRACTORBEAM_BRANCH`. |
