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

# Turbo CLI Reference

> Complete reference for all Turbo CLI commands including apply, list, delete, validate, logs, and inspect

## Pipeline management

### Apply a pipeline

Deploy a pipeline from a YAML configuration file:

```bash theme={null}
goldsky turbo apply my-pipeline.yaml
```

This command will:

* Validate your pipeline configuration
* Create or update the pipeline in your current project
* Start processing data according to your configuration

If a pipeline with the same name already exists, `apply` performs a server-side upsert that preserves checkpoints.

#### Options

| Flag                | Description                                                               |
| ------------------- | ------------------------------------------------------------------------- |
| `-i, --inspect`     | Open the inspect TUI after successful deployment to monitor live data     |
| `--skip-validation` | Skip server-side validation before deploying (validation runs by default) |

```bash theme={null}
# Deploy and immediately start inspecting live data
goldsky turbo apply my-pipeline.yaml -i
```

<Warning>
  To have a pipeline restart from scratch, you will have to rename the pipeline or rename the specific source node to avoid using the existing checkpoints.
</Warning>

### List pipelines

View all pipelines in your current project:

```bash theme={null}
goldsky turbo list
```

#### Options

| Flag           | Description                                                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `-o, --output` | Output format: `table`, `json`, or `yaml` (default: `table`). `json` and `yaml` include the full pipeline definition. |
| `--local-time` | Display timestamps in local timezone instead of UTC                                                                   |

### Get a pipeline

Fetch details for a single pipeline by name or YAML file:

```bash theme={null}
# Get pipeline definition as YAML
goldsky turbo get my-pipeline

# Print as JSON
goldsky turbo get my-pipeline -o json
```

#### Options

| Flag           | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| `-o, --output` | Output format: `yaml`, `json`, or `table` (default: `yaml`) |

### Delete a pipeline

Remove a pipeline by name:

```bash theme={null}
goldsky turbo delete my-pipeline
```

Or delete using the YAML file:

```bash theme={null}
goldsky turbo delete -f my-pipeline.yaml
```

#### Options

| Flag            | Description                                                                                                                                                                            |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-f, --file`    | Path to YAML file to extract the pipeline name from (mutually exclusive with the positional name)                                                                                      |
| `--clear-state` | Clear checkpoint state when deleting (default: `true`). Pass `--clear-state=false` to retain state so that re-applying a pipeline with the same name resumes from the last checkpoint. |

### Validate a pipeline

Check your pipeline configuration without deploying:

```bash theme={null}
goldsky turbo validate my-pipeline.yaml
```

This is useful for:

* Catching syntax errors before deployment
* Verifying source and sink configurations
* Testing transform logic

### Pause a pipeline

Temporarily stop a running pipeline:

```bash theme={null}
goldsky turbo pause my-pipeline
```

Or pause using the YAML file:

```bash theme={null}
goldsky turbo pause -f my-pipeline.yaml
```

This command sets deployment replicas to 0 or suspends jobs, preserving the pipeline state for later resumption.

#### Options

| Flag         | Description                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `-f, --file` | Path to YAML file to extract the pipeline name from (mutually exclusive with the positional name) |

### Resume a pipeline

Resume a previously paused pipeline:

```bash theme={null}
goldsky turbo resume my-pipeline
```

Or resume using the YAML file:

```bash theme={null}
goldsky turbo resume -f my-pipeline.yaml
```

This command restores the pipeline to its running state:

* For deployments: restores the replica count from the original pipeline configuration (defaults to 1 if not specified)
* For jobs: sets `suspend` to `false`

#### Options

| Flag         | Description                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `-f, --file` | Path to YAML file to extract the pipeline name from (mutually exclusive with the positional name) |

<Note>
  You can only resume a paused pipeline. Attempting to resume an already running pipeline will return an error.
</Note>

### Restart a pipeline

Restart a running or paused pipeline by triggering a pod restart:

```bash theme={null}
goldsky turbo restart my-pipeline
```

Or restart using the YAML file:

```bash theme={null}
goldsky turbo restart -f my-pipeline.yaml
```

To clear all state data and start fresh from the beginning:

```bash theme={null}
goldsky turbo restart my-pipeline --clear-state
```

#### Options

| Flag            | Description                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `-f, --file`    | Path to YAML file to extract the pipeline name from (mutually exclusive with the positional name)                   |
| `--clear-state` | Clear all checkpoint state so the pipeline reprocesses from the beginning (default: `false`, which preserves state) |
| `--resync`      | Re-deploy the original pipeline definition instead of a rolling pod restart (default: `false`)                      |

This command triggers a pod restart for the pipeline. If the pipeline is paused, it will automatically resume before restarting.

<Note>
  **Restart vs Resume**: Use `resume` to restore a paused pipeline without restarting pods. Use `restart` when you need to trigger a fresh pod restart, such as after configuration changes or to recover from issues. The `--clear-state` flag allows you to discard all checkpoints and reprocess data from the beginning.
</Note>

<Warning>
  Restart is not supported for Job-mode pipelines. Use `delete` and `apply` to recreate the job instead.
</Warning>

## Viewing logs

Monitor your pipeline's execution with the logs command:

```bash theme={null}
# View recent logs (default: last 10 lines when not following)
goldsky turbo logs my-pipeline

# Follow logs in real-time
goldsky turbo logs my-pipeline -f

# Show last 50 lines
goldsky turbo logs my-pipeline --tail 50

# Show logs from last hour
goldsky turbo logs my-pipeline --since 3600

# Include timestamps
goldsky turbo logs my-pipeline --timestamps

# Emit structured JSON log lines (useful for piping)
goldsky turbo logs my-pipeline -o json
```

#### Options

| Flag                | Description                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------------- |
| `-f, --follow`      | Stream new log lines as they are produced (like `kubectl logs -f`)                                              |
| `--tail <N>`        | Number of lines from the end of the logs to show. Defaults to `10` when `--follow` is not set, otherwise unset. |
| `--since <SECONDS>` | Show logs from the last N seconds                                                                               |
| `--timestamps`      | Include timestamps on each line                                                                                 |
| `-o, --output`      | Output format: `plaintext` or `json` (default: `plaintext`)                                                     |

<Tip>
  Use `-f` / `--follow` to monitor your pipeline in real-time, especially useful when debugging or watching data flow through transforms. `--follow` is supported for streaming deployments; Job-mode pipelines emit their logs up to completion and then terminate (the pipeline is auto-deleted 1 hour after termination).
</Tip>

## Inspecting live data

Open an interactive TUI to view live data flowing through your pipeline:

```bash theme={null}
# Inspect all nodes in a pipeline
goldsky turbo inspect my-pipeline

# Filter to specific topology nodes
goldsky turbo inspect my-pipeline -n source1,transform1

# Adjust buffer size for more history
goldsky turbo inspect my-pipeline -b 50000

# Print to stdout instead of TUI (for piping to other tools)
goldsky turbo inspect my-pipeline --print

# Pipe to jq for filtering
goldsky turbo inspect my-pipeline -p | jq '.data'
```

#### Options

| Flag                       | Description                                                     |
| -------------------------- | --------------------------------------------------------------- |
| `-n, --topology-node-keys` | Comma-separated list of topology node keys to filter (optional) |
| `-b, --buffer-size`        | Maximum records to keep in buffer (default: `10000`)            |
| `-p, --print`              | Print records to stdout instead of opening the TUI              |

The positional argument accepts either a pipeline name or a path to a YAML file (the name is read from the file's `name` field).

#### Keyboard shortcuts

| Key                   | Action                                     |
| --------------------- | ------------------------------------------ |
| `Tab` / `Shift+Tab`   | Next / previous topology node tab          |
| `←` `→` / `h` `l`     | Previous / next topology node tab          |
| `1`–`9`               | Jump directly to the Nth tab               |
| `↑` `↓` / `k` `j`     | Scroll up / down                           |
| `PageUp` / `PageDown` | Scroll by a page                           |
| `Home` / `g`          | Jump to top                                |
| `End` / `G`           | Jump to bottom                             |
| `/`                   | Start search                               |
| `n` / `N`             | Next / previous search match               |
| `Esc`                 | Clear active search, otherwise quit        |
| `d`                   | Toggle pipeline definition view            |
| `w`                   | Open pipeline in the Goldsky web dashboard |
| `e`                   | Open pipeline in the Goldsky web editor    |
| `q`                   | Quit                                       |

The TUI automatically reconnects if the pipeline is updated or temporarily unavailable, with a 30-minute timeout for persistent connection failures.

<Info>
  For detailed information about Live Inspect, including all keyboard shortcuts and features, see the [Live Inspect](/turbo-pipelines/live-inspect) guide.
</Info>

## Inspecting pipeline state

List checkpoint state entries for a pipeline:

```bash theme={null}
# By pipeline name
goldsky turbo state list my-pipeline

# By YAML file (name is read from the file)
goldsky turbo state list my-pipeline.yaml
```

This is primarily useful when debugging checkpoint-related behavior or confirming what state would be cleared by `--clear-state`.

## Managing projects and secrets

The Turbo Pipelines CLI integrates with the Goldsky CLI for project management. Any command that is not a Turbo pipeline subcommand is forwarded to the `goldsky` CLI on your PATH.

### Projects

```bash theme={null}
# List all projects you are a member of
goldsky project list
```

To log into a project you will need to generate an API key and run the `goldsky login` command.

### Secrets

Secrets are used to store sensitive configuration like database credentials:

```bash theme={null}
# Create a secret
goldsky secret create MY_POSTGRES_SECRET

# List secrets
goldsky secret list

# Delete a secret
goldsky secret delete MY_POSTGRES_SECRET
```

<Info>
  Secrets are referenced in your pipeline YAML using the `secret_name` field. See the [Pipeline Configuration](/turbo-pipelines/pipeline-config) guide for examples.
</Info>