0
# Command Line Interface
1
2
The `swift` command-line client provides complete Swift functionality from the terminal, offering an alternative to the Python API for all Swift operations including upload, download, listing, and management tasks.
3
4
## Capabilities
5
6
### Basic Authentication
7
8
All CLI commands support comprehensive authentication options.
9
10
```bash { .api }
11
swift --help
12
swift --os-username <user> --os-password <password> --os-auth-url <auth_url> <command>
13
swift --os-storage-url <url> --os-auth-token <token> <command>
14
```
15
16
Common authentication environment variables:
17
- `OS_USERNAME`, `OS_PASSWORD`
18
- `OS_AUTH_URL`, `OS_AUTH_VERSION`
19
- `OS_TENANT_NAME`, `OS_PROJECT_NAME`
20
- `OS_STORAGE_URL`, `OS_AUTH_TOKEN`
21
22
### Object Operations
23
24
Upload, download, and manage objects in Swift containers.
25
26
```bash { .api }
27
# Upload files and directories
28
swift upload <container> <file_or_dir> [<file_or_dir>] [...]
29
--object-name <object_name> # Custom object name
30
--segment-size <size> # Large object segment size
31
--use-slo # Use Static Large Objects
32
--segment-container <container> # Custom segment container
33
--header <header:value> # Custom headers
34
--meta <name:value> # Object metadata
35
--object-threads <threads> # Upload threads (default 10)
36
37
# Download objects
38
swift download <container> [<object>] [...]
39
--all # Download all objects
40
--marker <marker> # Start after this object
41
--prefix <prefix> # Objects starting with prefix
42
--output-dir <dir> # Download directory
43
--object-threads <threads> # Download threads (default 10)
44
--container-threads <threads> # Container threads (default 10)
45
--no-download # List only, don't download
46
--remove-prefix # Remove prefix from local names
47
--header <header:value> # Custom request headers
48
49
# Delete objects
50
swift delete <container> [<object>] [...]
51
--all # Delete all containers and objects
52
--leave-segments # Don't delete manifest segments
53
--object-threads <threads> # Delete threads (default 10)
54
--container-threads <threads> # Container threads (default 10)
55
--prefix <prefix> # Delete objects with prefix
56
--versions # Delete all object versions
57
--version-id <id> # Delete specific version
58
--header <header:value> # Custom request headers
59
60
# Copy objects
61
swift copy <container> <object> [...]
62
--destination <dest_container/dest_object> # Copy destination
63
--fresh-metadata # Replace metadata, don't merge
64
--meta <name:value> # Set metadata on copy
65
--header <header:value> # Custom request headers
66
```
67
68
### Container Operations
69
70
Create, list, and manage Swift containers.
71
72
```bash { .api }
73
# List containers and objects
74
swift list [<container>]
75
--long # Long listing format
76
--totals # Show totals
77
--prefix <prefix> # Filter by prefix
78
--delimiter <delimiter> # Delimiter for pseudo-directories
79
--marker <marker> # Start listing after marker
80
--end-marker <marker> # Stop listing before marker
81
--limit <limit> # Limit number of results
82
--header <header:value> # Custom request headers
83
84
# Update container/object metadata
85
swift post <container> [<object>]
86
--read-acl <acl> # Container read ACL
87
--write-acl <acl> # Container write ACL
88
--sync-to <container> # Container sync destination
89
--sync-key <key> # Container sync key
90
--meta <name:value> # Set metadata
91
--header <header:value> # Custom headers
92
--versions-location <container> # Enable versioning
93
--history-location <container> # Set history location
94
```
95
96
### Information and Statistics
97
98
Get detailed information about accounts, containers, and objects.
99
100
```bash { .api }
101
# Show statistics
102
swift stat [<container>] [<object>]
103
--lh # Human readable sizes
104
--header <header:value> # Custom request headers
105
--version-id <id> # Show specific version
106
107
# Show capabilities
108
swift capabilities [<url>]
109
--json # Output in JSON format
110
111
# Show authentication info
112
swift auth
113
--json # Output in JSON format
114
```
115
116
### Advanced Features
117
118
Generate temporary URLs and enable shell completion.
119
120
```bash { .api }
121
# Generate temporary URLs
122
swift tempurl <method> <seconds> <path> <key>
123
--absolute # Use absolute expiration time
124
--prefix-based # Allow prefix-based access
125
--iso8601 # Use ISO 8601 timestamp format
126
--ip-range <range> # Restrict to IP range
127
--digest <algorithm> # Digest algorithm (sha1, sha256, sha512)
128
129
# Enable bash completion
130
swift bash_completion
131
```
132
133
## Usage Examples
134
135
### Basic Object Management
136
137
```bash
138
# Set authentication via environment variables
139
export OS_USERNAME=myuser
140
export OS_PASSWORD=mypass
141
export OS_AUTH_URL=https://identity.example.com:5000/v3
142
export OS_PROJECT_NAME=myproject
143
export OS_USER_DOMAIN_NAME=mydomain
144
export OS_PROJECT_DOMAIN_NAME=mydomain
145
146
# List all containers
147
swift list
148
149
# Create a container and upload a file
150
swift upload documents report.pdf
151
152
# Download all objects from a container
153
swift download documents
154
155
# List objects in a container with details
156
swift list --long documents
157
158
# Get container statistics
159
swift stat documents
160
161
# Delete an object
162
swift delete documents report.pdf
163
```
164
165
### Large File Uploads
166
167
```bash
168
# Upload large file using Static Large Objects
169
swift upload videos --use-slo --segment-size 100M movie.mp4
170
171
# Upload directory with custom segment container
172
swift upload backups --segment-container backup-segments /path/to/data/
173
```
174
175
### Temporary URLs
176
177
```bash
178
# Generate 1-hour temporary download URL
179
swift tempurl GET 3600 /v1/AUTH_account/container/object.jpg secret_key
180
181
# Generate temporary upload URL with IP restriction
182
swift tempurl PUT 1800 /v1/AUTH_account/uploads/newfile.dat upload_key --ip-range 192.168.1.0/24
183
```
184
185
### Bulk Operations
186
187
```bash
188
# Download all objects matching a prefix
189
swift download --prefix photos/2023/ gallery
190
191
# Delete all objects in a container
192
swift delete --all mycontainer
193
194
# Upload multiple files with metadata
195
swift upload docs --meta category:reports *.pdf
196
```
197
198
### Container Sync and Versioning
199
200
```bash
201
# Enable container versioning
202
swift post container --versions-location container-versions
203
204
# Set up container sync
205
swift post source-container --sync-to target-container --sync-key sync_secret
206
207
# Set container ACLs
208
swift post public-container --read-acl ".r:*,.rlistings"
209
```
210
211
## Global Options
212
213
All commands support these global authentication and configuration options:
214
215
```bash { .api }
216
--os-username <username> # OpenStack username
217
--os-password <password> # OpenStack password
218
--os-tenant-name <tenant> # OpenStack tenant name
219
--os-auth-url <auth_url> # OpenStack auth URL
220
--os-auth-version <version> # Auth version (1, 2, 3)
221
--os-storage-url <url> # Storage URL (bypass auth)
222
--os-auth-token <token> # Auth token (bypass auth)
223
--os-region-name <region> # OpenStack region
224
--insecure # Allow insecure SSL connections
225
--no-ssl # Use HTTP instead of HTTPS
226
--ssl-compression # Enable SSL compression
227
--retries <count> # Number of retries (default 5)
228
--retry-on-ratelimit # Retry on rate limit responses
229
--timeout <seconds> # Connection timeout
230
--verbose # Verbose output
231
--debug # Debug output
232
--quiet # Suppress output
233
--json # JSON formatted output
234
```