0
# Upload and Deployment
1

2
Upload packaged CLIs to AWS S3 and manage distribution channels for automatic updates and releases.
3

4
## Capabilities
5

6
### Upload Tarballs
7

8
Upload compressed tarballs to S3 for distribution and automatic updates.
9

10
```bash { .api }
11
oclif upload tarballs
12
```
13

14
**Flags:**
15
- `--root`, `-r` (string) - Root directory of the CLI project (default: ".")
16
- `--targets`, `-t` (string) - Comma-separated targets to upload
17
- `--xz` (boolean) - Also upload xz compressed tarballs
18
- `--sha` (string) - Git SHA to include in upload metadata
19
- `--dry-run` (boolean) - Run without uploading to S3
20

21
**Usage Examples:**
22

23
```bash
24
# Upload all tarballs to S3
25
oclif upload tarballs
26

27
# Upload specific targets
28
oclif upload tarballs --targets=linux-x64,darwin-x64
29

30
# Upload with xz compression
31
oclif upload tarballs --xz
32

33
# Uploads tarballs from ./dist/tarballs/ to configured S3 bucket
34
```
35

36
**Requirements:**
37
- AWS credentials configured (AWS CLI, environment variables, or IAM roles)
38
- S3 bucket and configuration set in package.json
39
- Tarballs must be built first using `oclif pack tarballs`
40

41
### Upload Debian Packages
42

43
Upload .deb packages to S3 for Debian/Ubuntu distribution.
44

45
```bash { .api }
46
oclif upload deb
47
```
48

49
**Flags:**
50
- `--root`, `-r` (string) - Root directory of the CLI project (default: ".")
51
- `--sha` (string) - Git SHA to include in upload metadata
52
- `--dry-run` (boolean) - Run without uploading to S3
53

54
**Usage Examples:**
55

56
```bash
57
# Upload Debian packages
58
oclif upload deb
59

60
# Upload with dry run
61
oclif upload deb --dry-run
62

63
# Uploads .deb files from ./dist/deb/ to S3
64
```
65

66
### Upload macOS Packages
67

68
Upload macOS installer packages to S3 for distribution.
69

70
```bash { .api }
71
oclif upload macos
72
```
73

74
**Flags:**
75
- `--root`, `-r` (string) - Root directory of the CLI project (default: ".")
76
- `--targets`, `-t` (string) - Comma-separated targets to upload
77
- `--sha` (string) - Git SHA to include in upload metadata
78
- `--dry-run` (boolean) - Run without uploading to S3
79

80
**Usage Examples:**
81

82
```bash
83
# Upload macOS installers
84
oclif upload macos
85

86
# Upload specific targets
87
oclif upload macos --targets=darwin-x64,darwin-arm64
88

89
# Uploads .pkg files from ./dist/macos/ to S3
90
```
91

92
### Upload Windows Packages
93

94
Upload Windows installer packages to S3 for distribution.
95

96
```bash { .api }
97
oclif upload win
98
```
99

100
**Flags:**
101
- `--root`, `-r` (string) - Root directory of the CLI project (default: ".")
102
- `--targets` (string) - Comma-separated targets to upload
103
- `--sha` (string) - Git SHA to include in upload metadata
104
- `--dry-run` (boolean) - Run without uploading to S3
105

106
**Usage Examples:**
107

108
```bash
109
# Upload Windows installers
110
oclif upload win
111

112
# Upload specific targets
113
oclif upload win --targets=win32-x64,win32-x86
114

115
# Uploads .exe and .msi files from ./dist/win32/ to S3
116
```
117

118
### Promote Releases
119

120
Promote CLI builds to release channels for controlled distribution and staged rollouts.
121

122
```bash { .api }
123
oclif promote
124
```
125

126
**Flags:**
127
- `--channel` (string) - Release channel (stable, beta, alpha) (default: "stable")
128
- `--version` (string) - Semantic version to promote (required)
129
- `--sha` (string) - 7-digit short git commit SHA to promote (required)
130
- `--root`, `-r` (string) - Root directory of the CLI project (default: ".")
131
- `--targets`, `-t` (string) - Comma-separated list of targets to promote
132
- `--deb`, `-d` (boolean) - Promote Debian packages
133
- `--macos`, `-m` (boolean) - Promote macOS packages
134
- `--win`, `-w` (boolean) - Promote Windows packages
135
- `--xz` (boolean) - Also promote xz compressed tarballs
136
- `--indexes` (boolean) - Append promoted URLs to index files
137
- `--max-age`, `-a` (string) - Cache control max-age in seconds (default: "86400")
138
- `--dry-run` (boolean) - Preview promotion without making changes
139
- `--ignore-missing` (boolean) - Continue promoting even if some artifacts are missing
140

141
**Usage Examples:**
142

143
```bash
144
# Promote current version to stable channel
145
oclif promote --channel=stable
146

147
# Promote specific version and SHA
148
oclif promote --version=1.2.3 --sha=abc123 --channel=beta
149

150
# Promote with dry run to preview changes
151
oclif promote --channel=stable --dry-run
152

153
# Promote specific platforms only
154
oclif promote --targets=linux-x64,darwin-x64 --macos --channel=stable
155
```
156

157
## AWS S3 Integration
158

159
oclif provides comprehensive S3 integration for hosting and distributing CLI packages.
160

161
### S3 Operations
162

163
```typescript { .api }
164
interface AWSS3Operations {
165
  /** Upload file to S3 with progress tracking */
166
  uploadFile(
167
    localPath: string, 
168
    options: S3UploadOptions,
169
    config?: S3Config
170
  ): Promise<void>;
171

172
  /** Copy object within S3 */
173
  copyObject(
174
    options: S3CopyOptions,
175
    config?: S3Config
176
  ): Promise<void>;
177

178
  /** Get object metadata */
179
  headObject(options: S3HeadOptions): Promise<S3HeadResult>;
180

181
  /** Get object content */
182
  getObject(options: S3GetOptions): Promise<S3GetResult>;
183

184
  /** List objects in bucket */
185
  listObjects(options: S3ListOptions): Promise<S3ListResult>;
186

187
  /** Delete multiple objects */
188
  deleteObjects(options: S3DeleteOptions): Promise<void>;
189
}
190

191
interface S3UploadOptions {
192
  bucket: string;
193
  key: string;
194
  acl?: string;
195
  contentType?: string;
196
  metadata?: Record<string, string>;
197
}
198

199
interface S3CopyOptions {
200
  sourceBucket: string;
201
  sourceKey: string;
202
  destinationBucket: string;
203
  destinationKey: string;
204
  acl?: string;
205
}
206
```
207

208
### CloudFront Integration
209

210
```typescript { .api }
211
interface CloudFrontOperations {
212
  /** Create CloudFront cache invalidation */
213
  createCloudfrontInvalidation(options: CloudFrontInvalidationOptions): Promise<void>;
214
}
215

216
interface CloudFrontInvalidationOptions {
217
  distributionId: string;
218
  paths: string[];
219
  callerReference?: string;
220
}
221
```
222

223
## Update Mechanism
224

225
oclif supports automatic updates through S3-hosted version manifests and update channels.
226

227
### Update Configuration
228

229
```typescript { .api }
230
interface UpdateConfiguration {
231
  /** Automatic update settings */
232
  autoupdate?: {
233
    /** Rollout percentage (0-100) */
234
    rollout: number;
235
    /** Debounce time in minutes */
236
    debounce: number;
237
  };
238
  /** Node.js runtime version */
239
  node?: {
240
    version: string;
241
  };
242
  /** S3 hosting configuration */
243
  s3?: {
244
    bucket: string;
245
    /** S3 key prefix/folder */
246
    folder?: string;
247
    /** Custom host URL for downloads */
248
    host?: string;
249
    /** S3 ACL permissions */
250
    acl?: string;
251
    /** Maximum versions to keep in index */
252
    indexVersionLimit?: number;
253
    /** Use xz compression */
254
    xz?: boolean;
255
  };
256
}
257
```
258

259
### Release Channels
260

261
oclif supports multiple release channels for staged rollouts:
262

263
- **stable**: Production releases
264
- **beta**: Pre-release testing
265
- **alpha**: Early development builds
266
- **dev**: Development builds
267

268
### Version Indexes
269

270
Version indexes track available versions and update metadata:
271

272
```typescript { .api }
273
interface VersionIndex {
274
  /** Channel name */
275
  channel: string;
276
  /** Available versions */
277
  versions: VersionMetadata[];
278
  /** Current/latest version */
279
  current: string;
280
}
281

282
interface VersionMetadata {
283
  version: string;
284
  sha: string;
285
  date: string;
286
  /** Platform-specific download URLs */
287
  downloads: Record<Target, DownloadInfo>;
288
}
289

290
interface DownloadInfo {
291
  url: string;
292
  sha256: string;
293
  size: number;
294
}
295
```
296

297
## Upload Utilities
298

299
Helper functions for upload and deployment operations.
300

301
```typescript { .api }
302
/**
303
 * Check if endpoint is S3-compatible
304
 * @param endpoint - S3 endpoint URL
305
 * @returns True if endpoint supports S3 API
306
 */
307
function isS3Compatible(endpoint: string): boolean;
308

309
/**
310
 * Get S3 checksum configuration
311
 * @param endpoint - S3 endpoint
312
 * @param envValue - Environment variable value
313
 * @returns S3 checksum settings
314
 */
315
function getS3ChecksumConfig(
316
  endpoint: string, 
317
  envValue?: string
318
): S3ChecksumConfig;
319

320
interface S3ChecksumConfig {
321
  algorithm: 'SHA256' | 'SHA1' | 'CRC32' | 'CRC32C';
322
  enabled: boolean;
323
}
324
```
325

326
## Deployment Workflow
327

328
Typical deployment workflow for oclif CLIs:
329

330
1. **Build**: `oclif pack tarballs --targets=linux-x64,darwin-x64,win32-x64`
331
2. **Upload**: `oclif upload tarballs`
332
3. **Promote**: `oclif promote --channel=beta`
333
4. **Test**: Verify beta channel functionality
334
5. **Release**: `oclif promote --channel=stable`
335

336
### Environment Variables
337

338
Required environment variables for S3 operations:
339

340
```bash
341
# AWS credentials
342
AWS_ACCESS_KEY_ID=your-access-key
343
AWS_SECRET_ACCESS_KEY=your-secret-key
344
AWS_REGION=us-east-1
345

346
# Optional: Custom S3 endpoint
347
AWS_S3_ENDPOINT=https://s3.custom-domain.com
348

349
# Optional: CloudFront distribution
350
CLOUDFRONT_DISTRIBUTION_ID=ABCDEFGHIJKLMN
351
```
352

353
### Package.json S3 Configuration
354

355
```json { .api }
356
{
357
  "oclif": {
358
    "update": {
359
      "s3": {
360
        "bucket": "my-cli-releases",
361
        "folder": "releases/mycli",
362
        "host": "https://releases.mycli.com",
363
        "acl": "public-read",
364
        "indexVersionLimit": 20,
365
        "xz": true
366
      },
367
      "autoupdate": {
368
        "rollout": 100,
369
        "debounce": 60
370
      }
371
    }
372
  }
373
}
374
```