0
# Remote Cache Integration
1

2
Authentication and linking with Vercel's remote cache infrastructure for team collaboration, enabling shared build artifacts across development environments and CI/CD pipelines.
3

4
## Capabilities
5

6
### Authentication
7

8
Authenticate with Vercel to enable remote cache access and team collaboration features.
9

10
```bash { .api }
11
turbo login [options]
12

13
# Basic authentication
14
turbo login
15

16
# SSO team authentication
17
turbo login --sso-team=my-team
18

19
# Force new token generation
20
turbo login --force
21

22
# Manual token entry
23
turbo login --manual
24
```
25

26
**Login Options:**
27

28
```bash { .api }
29
--sso-team <team>                  # SSO team slug for authentication
30
--force / -f                       # Force new token, overwrite existing
31
--manual                          # Manual token entry instead of browser flow
32
```
33

34
**Usage Examples:**
35

36
```bash
37
# Standard login flow (opens browser)
38
turbo login
39

40
# Login with specific SSO team
41
turbo login --sso-team=acme-corp
42

43
# Force re-authentication
44
turbo login --force
45

46
# Enter token manually (for CI/headless environments)
47
turbo login --manual
48
```
49

50
### Logout
51

52
Deauthenticate from Vercel and optionally invalidate tokens on the server.
53

54
```bash { .api }
55
turbo logout [options]
56

57
# Basic logout
58
turbo logout
59

60
# Logout and invalidate token on server
61
turbo logout --invalidate
62
```
63

64
**Logout Options:**
65

66
```bash { .api }
67
--invalidate                       # Invalidate token on server (recommended for security)
68
```
69

70
**Usage Examples:**
71

72
```bash
73
# Standard logout (keeps token valid on server)
74
turbo logout
75

76
# Secure logout that invalidates token
77
turbo logout --invalidate
78
```
79

80
### Link Repository
81

82
Link your local repository to a Vercel organization to enable remote caching and team features.
83

84
```bash { .api }
85
turbo link [options]
86

87
# Interactive linking
88
turbo link
89

90
# Link with specific scope
91
turbo link --scope=my-team
92

93
# Auto-confirm prompts
94
turbo link --yes
95

96
# Link without modifying .gitignore
97
turbo link --no-gitignore
98
```
99

100
**Link Options:**
101

102
```bash { .api }
103
--scope <scope>                    # Vercel team/organization scope
104
--yes / -y                         # Auto-confirm all prompts
105
--no-gitignore                     # Don't modify .gitignore file
106
--target <target>                  # DEPRECATED: Link target specification
107
```
108

109
**Usage Examples:**
110

111
```bash
112
# Interactive linking with prompts
113
turbo link
114

115
# Link to specific organization
116
turbo link --scope=acme-corp --yes
117

118
# Link without modifying .gitignore
119
turbo link --no-gitignore
120

121
# Quick link for automation
122
turbo link --scope=my-team --yes
123
```
124

125
### Unlink Repository
126

127
Unlink your repository from Vercel organization and disable remote caching.
128

129
```bash { .api }
130
turbo unlink [options]
131

132
# Basic unlinking
133
turbo unlink
134

135
# Unlink with deprecated target option
136
turbo unlink --target=remote-cache
137
```
138

139
**Unlink Options:**
140

141
```bash { .api }
142
--target <target>                  # DEPRECATED: Unlink target specification
143
```
144

145
**Usage Examples:**
146

147
```bash
148
# Standard repository unlinking
149
turbo unlink
150

151
# Unlink for CI cleanup
152
turbo unlink --target=remote-cache
153
```
154

155
### Remote Cache Configuration
156

157
Configure remote cache behavior through global options and configuration files.
158

159
```bash { .api }
160
# Global remote cache options
161
--api <url>                        # Override API endpoint
162
--team <slug>                      # Set team slug for requests
163
--token <token>                    # Set authentication token
164
--remote-cache-timeout <seconds>   # Set HTTP request timeout
165
--preflight                        # Enable OPTIONS preflight requests
166

167
# Usage with task execution
168
turbo run build --team=acme-corp --remote-cache-timeout=60
169
```
170

171
**Configuration Examples:**
172

173
```bash
174
# Use custom API endpoint
175
turbo run build --api=https://custom-api.example.com
176

177
# Set team context for remote cache
178
turbo run build --team=my-team
179

180
# Configure timeout for slow networks
181
turbo run build --remote-cache-timeout=120
182

183
# Enable preflight requests for CORS
184
turbo run build --preflight
185
```
186

187
### Remote Cache Access Control
188

189
Control how remote cache is accessed during task execution.
190

191
```bash { .api }
192
# Remote cache access modes (used with --cache option)
193
remote:r          # Read-only remote cache access
194
remote:w          # Write-only remote cache access  
195
remote:rw         # Read-write remote cache access
196

197
# Shorthand options
198
--remote-only                      # Equivalent to --cache=remote:rw
199
--remote-cache-read-only           # Equivalent to --cache=local:rw,remote:r
200

201
# Examples
202
turbo run build --remote-only
203
turbo run build --remote-cache-read-only
204
turbo run build --cache=remote:r
205
```
206

207
**Usage Examples:**
208

209
```bash
210
# Use only remote cache (no local cache)
211
turbo run build --remote-only
212

213
# Read from remote, write to local only
214
turbo run build --remote-cache-read-only
215

216
# Read from remote, write to both local and remote
217
turbo run build --cache=local:rw,remote:r
218

219
# Write results to remote cache only
220
turbo run build --cache=remote:w
221
```
222

223
## Authentication Types
224

225
```typescript { .api }
226
interface LoginOptions {
227
  sso_team?: string;
228
  force: boolean;
229
  manual: boolean;
230
}
231

232
interface LogoutOptions {
233
  invalidate: boolean;
234
}
235

236
interface LinkOptions {
237
  scope?: string;
238
  yes: boolean;
239
  no_gitignore: boolean;
240
  target?: "remote-cache" | "spaces";  // DEPRECATED
241
}
242

243
interface UnlinkOptions {
244
  target?: "remote-cache" | "spaces";  // DEPRECATED
245
}
246

247
interface APIAuth {
248
  team_id?: string;
249
  token: string;
250
  team_slug?: string;
251
}
252

253
interface RemoteCacheOptions {
254
  api_url: string;
255
  timeout: number;
256
  upload_timeout: number;
257
  preflight: boolean;
258
  team_id?: string;
259
  team_slug?: string;
260
  token?: string;
261
}
262

263
interface CacheCredentials {
264
  token: string;
265
  team_id?: string;
266
  team_slug?: string;
267
  expires_at?: string;
268
}
269
```
270

271
## Team Collaboration
272

273
Remote caching enables several team collaboration workflows:
274

275
**Shared Cache Benefits:**
276
- Developers can share build artifacts across machines
277
- CI/CD pipelines can reuse artifacts from previous builds
278
- New team members get faster initial builds
279
- Reduces compute costs in cloud environments
280

281
**Access Control:**
282
- Team-based access to cached artifacts  
283
- Token-based authentication with expiration
284
- Read-only access for CI environments
285
- Full read-write access for development
286

287
**Best Practices:**
288
- Use `--remote-cache-read-only` in CI for security
289
- Set appropriate timeouts for network conditions
290
- Link repositories at the organization level
291
- Invalidate tokens when team members leave