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

# nsc cache turborepo setup

Set up Turborepo remote caching and output the required environment variables.

Namespace provides high-performance [Turborepo](https://turbo.build) remote caching, backed by storage running alongside your jobs.
`cache turborepo setup` issues a short-lived cache token and prints the `TURBO_*` environment variables that `turbo` needs to talk to the Namespace cache.

The command does not modify your repository or shell: it writes `KEY=value` lines to stdout, so you can export them locally or append them to a CI environment file.

[Learn more about Turborepo caching →](/docs/integrations/turborepo)

## Usage

```bash theme={null}
nsc cache turborepo setup --team <team> \
    [--mask-auto] \
    [--mask-buildkite] \
    [--mask-github-actions] \
    [--output <plain|json>] \
    [--read-only] \
    [--token <path>] \
    [--token_duration <duration>]
```

### Example output

```bash theme={null}
nsc cache turborepo setup --team main
```

```text nocopy Output theme={null}
TURBO_API=https://turbo.cache.namespaceapi.com
TURBO_TEAM=main
TURBO_TOKEN=nsct_...
```

### Example in a local shell

Export the generated configuration into your shell, then run `turbo` as usual:

```bash theme={null}
export $(nsc cache turborepo setup --team main)
turbo build
```

### Example in GitHub Actions

Append the generated configuration to `$GITHUB_ENV` so that subsequent steps pick it up:

```bash theme={null}
nsc cache turborepo setup --team main --mask-github-actions >> "$GITHUB_ENV"
```

### Example in Buildkite

Register the token with the Buildkite redactor and export the configuration for the rest of the step:

```bash theme={null}
export $(nsc cache turborepo setup --team main --mask-buildkite)
turbo build
```

## Options

<h3 id="--team-team">
  \--team \<team>
</h3>

The Turborepo team to use. Teams isolate caches from each other, so different projects can share a workspace without sharing cache entries.

This flag is required. Use [`nsc cache turborepo list`](/docs/reference/cli/cache-turborepo-list) to see the teams that already have cached artifacts.

<h3 id="--read-only">
  \--read-only
</h3>

Only read from the remote cache. Sets `TURBO_CACHE=local:rw,remote:r` in the generated configuration, so `turbo` still writes to the local cache but never uploads to the remote one.

Use this for workloads that should benefit from the cache without being able to poison it, such as builds of untrusted pull requests. To enforce read-only access on the server side as well, run the command with a token that only carries the `read` action:

```bash theme={null}
nsc token create \
  --name "turborepo-cache-read-only" \
  --grant '{"resource_type":"cache/turborepo","resource_id":"*","actions":["read"]}'
```

See [Permissions](/docs/security/permissions#cacheturborepo) for the full list of `cache/turborepo` actions.

<h3 id="--mask-buildkite">
  \--mask-buildkite
</h3>

Mask the generated token in Buildkite, so it is redacted from job logs.

Requires `buildkite-agent` on `PATH`; the command fails if it is not found.

<h3 id="--mask-github-actions">
  \--mask-github-actions
</h3>

Mask the generated token in GitHub Actions, so it is redacted from workflow logs.

<h3 id="--mask-auto">
  \--mask-auto
</h3>

Mask the generated token in a detected CI environment. Supported environments are GitHub Actions and Buildkite. Use this when the same script runs in more than one CI system.

<h3 id="--output--o-format">
  \--output, -o \<format>
</h3>

Output format. One of `plain` or `json`. Default is `plain`.

`json` emits the same values as an object, which is convenient when a wrapper script needs to parse them:

```json theme={null}
{
  "api": "https://turbo.cache.namespaceapi.com",
  "team": "main",
  "token": "nsct_..."
}
```

<h3 id="--token_duration-duration">
  \--token\_duration \<duration>
</h3>

The minimum duration of the configured token. Default is `4h`. Raise it for jobs that run longer than the default token lifetime.

<h3 id="--token-path">
  \--token \<path>
</h3>

Use the bearer token stored at this location for authentication instead of the default.

## Related Topics

* [nsc cache turborepo list](/docs/reference/cli/cache-turborepo-list) - List teams with cached artifacts
* [nsc token create](/docs/reference/cli/token-create) - Create scoped, revokable tokens
* [Turborepo caching](/docs/integrations/turborepo) - Turborepo caching overview and CI setup
* [Permissions](/docs/security/permissions#cacheturborepo) - `cache/turborepo` resource types and actions