0
# Packaging
1

2
Package oclif CLIs into distributable formats including tarballs, installers, and platform-specific packages for cross-platform distribution.
3

4
## Capabilities
5

6
### Package Tarballs
7

8
Creates compressed tarballs containing the CLI and its dependencies for multiple target platforms.
9

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

14
**Flags:**
15
- `--parallel` (boolean) - Build targets in parallel for faster packaging
16
- `--prune-lockfiles` (boolean) - Remove lockfiles from packaged output
17
- `--root`, `-r` (string) - Root directory of the CLI project (default: ".")
18
- `--sha` (string) - Git SHA to include in package metadata  
19
- `--tarball`, `-l` (string) - Path to existing NPM tarball
20
- `--targets`, `-t` (string) - Comma-separated list of target platforms
21
- `--xz` (boolean) - Use xz compression instead of gzip
22

23
**Usage Examples:**
24

25
```bash
26
# Package for all default targets
27
oclif pack tarballs
28

29
# Package specific targets
30
oclif pack tarballs --targets=linux-x64,darwin-x64,win32-x64
31

32
# Package with parallel builds and xz compression
33
oclif pack tarballs --parallel --xz
34

35
# Package with custom SHA
36
oclif pack tarballs --sha=abc123def456
37
```
38

39
**Supported Targets:**
40

41
```typescript { .api }
42
type Target = 
43
  | 'linux-x64' | 'linux-arm' | 'linux-arm64'
44
  | 'darwin-x64' | 'darwin-arm64' 
45
  | 'win32-x64' | 'win32-x86' | 'win32-arm64';
46
```
47

48
### Package Debian
49

50
Creates .deb packages for Debian and Ubuntu distributions.
51

52
```bash { .api }
53
oclif pack deb
54
```
55

56
**Flags:**
57
- `--root`, `-r` (string) - Root directory of the CLI project (default: ".")
58
- `--compression`, `-z` (gzip|none|xz|zstd) - Override default compression
59
- `--prune-lockfiles` (boolean) - Remove lockfiles from packaged output
60
- `--sha` (string) - Git SHA to include in package metadata
61
- `--tarball`, `-t` (string) - Path to existing tarball
62

63
**Usage Examples:**
64

65
```bash
66
# Create Debian package
67
oclif pack deb
68

69
# Create with custom compression
70
oclif pack deb --compression=xz
71

72
# Package will be created in ./dist/deb/
73
```
74

75
**Debian Package Structure:**
76
- Creates `.deb` files in `./dist/deb/` directory
77
- Includes proper Debian control files and metadata
78
- Sets up appropriate file permissions and directories
79
- Configures post-install scripts for CLI registration
80

81
### Package macOS
82

83
Creates macOS installer packages (.pkg files) for distribution through the Mac App Store or direct download.
84

85
```bash { .api }
86
oclif pack macos
87
```
88

89
**Flags:**
90
- `--root`, `-r` (string) - Root directory of the CLI project (default: ".")
91
- `--additional-cli` (string) - Additional CLI to make available
92
- `--prune-lockfiles` (boolean) - Remove lockfiles from packaged output
93
- `--sha` (string) - Git SHA to include in package metadata
94
- `--tarball`, `-t` (string) - Path to existing tarball
95
- `--targets` (string) - Comma-separated targets to pack
96

97
**Usage Examples:**
98

99
```bash
100
# Create macOS installer
101
oclif pack macos
102

103
# Create for specific targets
104
oclif pack macos --targets=darwin-x64,darwin-arm64
105

106
# Installer will be created in ./dist/macos/
107
```
108

109
**macOS Package Features:**
110
- Creates signed `.pkg` installer files
111
- Supports macOS code signing and notarization
112
- Handles both Intel and Apple Silicon architectures
113
- Configures proper installation paths and permissions
114

115
### Package Windows
116

117
Creates Windows installer packages including MSI and executable installers.
118

119
```bash { .api }
120
oclif pack win
121
```
122

123
**Flags:**
124
- `--root`, `-r` (string) - Root directory of the CLI project (default: ".")
125
- `--additional-cli` (string) - Additional CLI to make available
126
- `--defender-exclusion` (checked|unchecked|hidden) - Windows Defender exclusion setting
127
- `--prune-lockfiles` (boolean) - Remove lockfiles from packaged output
128
- `--sha` (string) - Git SHA to include in package metadata
129
- `--tarball`, `-t` (string) - Path to existing tarball
130
- `--targets` (string) - Comma-separated targets to pack
131

132
**Usage Examples:**
133

134
```bash
135
# Create Windows installer
136
oclif pack win
137

138
# Create with Windows Defender exclusion
139
oclif pack win --defender-exclusion=checked
140

141
# Installers will be created in ./dist/win32/
142
```
143

144
**Windows Package Features:**
145
- Creates `.exe` and `.msi` installer files
146
- Supports Windows code signing
147
- Handles both x64 and x86 architectures
148
- Configures Windows registry entries and PATH updates
149

150
## Build Configuration
151

152
Packaging behavior is controlled through the oclif configuration and build settings.
153

154
### Build Config Interface
155

156
```typescript { .api }
157
interface BuildConfig {
158
  /** Root directory of the project */
159
  root: string;
160
  /** Target platforms to build for */
161
  targets: Target[];
162
  /** Git SHA for versioning */
163
  sha?: string;
164
  /** S3 configuration for uploads */
165
  s3Config?: S3Config;
166
  /** Update mechanism configuration */
167
  updateConfig?: UpdateConfig;
168
  /** Node.js version to bundle */
169
  nodeVersion?: string;
170
  /** Whether to use xz compression */
171
  xz?: boolean;
172
}
173

174
interface S3Config {
175
  bucket: string;
176
  folder?: string;
177
  host?: string;
178
  acl?: string;
179
  xz?: boolean;
180
}
181

182
interface UpdateConfig {
183
  autoupdate?: {
184
    /** Percentage rollout for updates */
185
    rollout?: number;
186
    /** Debounce time in minutes */
187
    debounce?: number;
188
  };
189
  /** Node.js configuration */
190
  node?: {
191
    version: string;
192
  };
193
  /** S3 update configuration */
194
  s3?: S3Config;
195
}
196
```
197

198
### Package.json Configuration
199

200
Configure packaging behavior in package.json:
201

202
```json { .api }
203
{
204
  "oclif": {
205
    "update": {
206
      "s3": {
207
        "bucket": "my-cli-releases",
208
        "folder": "releases",
209
        "host": "https://releases.mycli.com",
210
        "xz": true
211
      },
212
      "node": {
213
        "version": "18.17.1"
214
      }
215
    },
216
    "macos": {
217
      "identifier": "com.company.mycli"
218
    },
219
    "topics": {
220
      "pack": {
221
        "description": "Package CLI for distribution"
222
      }
223
    }
224
  },
225
  "files": [
226
    "oclif.manifest.json",
227
    "./bin",
228
    "./lib"
229
  ]
230
}
231
```
232

233
## Build Targets and Platforms
234

235
oclif supports building for multiple target platforms with specific Node.js versions and architectures.
236

237
### Available Targets
238

239
```typescript { .api }
240
const TARGETS: Target[] = [
241
  'linux-x64',    // Linux x86_64
242
  'linux-arm',    // Linux ARM 32-bit
243
  'linux-arm64',  // Linux ARM 64-bit
244
  'darwin-x64',   // macOS Intel
245
  'darwin-arm64', // macOS Apple Silicon
246
  'win32-x64',    // Windows x86_64
247
  'win32-x86',    // Windows x86 32-bit
248
  'win32-arm64'   // Windows ARM 64-bit
249
];
250
```
251

252
### Build Process
253

254
The packaging process involves several steps:
255

256
1. **Dependency Resolution**: Installs production dependencies
257
2. **Code Compilation**: Compiles TypeScript to JavaScript if needed
258
3. **Node.js Bundling**: Includes Node.js runtime for standalone execution
259
4. **Binary Creation**: Creates platform-specific executables
260
5. **Compression**: Applies gzip or xz compression
261
6. **Metadata Generation**: Includes version info and checksums
262

263
### Output Structure
264

265
Packaged files are organized in the `./dist/` directory:
266

267
```
268
dist/
269
├── channels/          # Update channel metadata
270
├── tarballs/         # Compressed tarballs
271
│   ├── mycli-v1.0.0-linux-x64.tar.gz
272
│   ├── mycli-v1.0.0-darwin-x64.tar.gz
273
│   └── mycli-v1.0.0-win32-x64.tar.gz
274
├── deb/              # Debian packages
275
│   └── mycli_1.0.0_amd64.deb
276
├── macos/            # macOS installers
277
│   └── mycli-v1.0.0.pkg
278
└── win32/            # Windows installers
279
    ├── mycli-v1.0.0-x64.exe
280
    └── mycli-v1.0.0-x64.msi
281
```
282

283
## Utility Functions
284

285
Helper functions for build configuration and packaging operations.
286

287
```typescript { .api }
288
/**
289
 * Create build configuration from project settings
290
 * @param root - Project root directory
291
 * @param options - Build options
292
 * @returns Complete build configuration
293
 */
294
function buildConfig(root: string, options?: BuildOptions): BuildConfig;
295

296
/**
297
 * Get current git SHA for versioning
298
 * @param cwd - Working directory
299
 * @param options - Git options
300
 * @returns Git SHA string
301
 */
302
function gitSha(cwd: string, options?: { short?: boolean }): string;
303

304
interface BuildOptions {
305
  targets?: Target[];
306
  sha?: string;
307
  xz?: boolean;
308
  parallel?: boolean;
309
}
310
```