0
# Command Line Tool
1

2
The xattr package includes a command-line tool for viewing and editing extended filesystem attributes from the shell. This tool provides a complete command-line interface for all extended attribute operations.
3

4
## Installation and Access
5

6
The command-line tool is automatically installed with the package and can be accessed in multiple ways:
7

8
```bash
9
# Direct command (after pip install xattr)
10
xattr [options] file [file ...]
11

12
# As Python module
13
python -m xattr [options] file [file ...]
14

15
# Using the tool module directly
16
python -m xattr.tool [options] file [file ...]
17
```
18

19
## Capabilities
20

21
### List Attributes (Default)
22

23
List the names of all extended attributes on files.
24

25
```bash { .api }
26
xattr [-slz] file [file ...]
27
```
28

29
**Parameters:**
30
- `file`: Path to file(s) to examine
31
- `-s`: Act on symbolic links themselves rather than their targets
32
- `-l`: Print long format (attr_name: attr_value)
33
- `-z`: Compress or decompress attribute values in zip format
34

35
**Usage Examples:**
36

37
```bash
38
# List attribute names for a file
39
xattr /path/to/file
40

41
# List attributes for multiple files
42
xattr file1.txt file2.txt /path/to/dir
43

44
# List attributes on symlink itself (not target)
45
xattr -s /path/to/symlink
46

47
# List in long format (show names and values)
48
xattr -l /path/to/file
49

50
# Handle compressed attributes
51
xattr -lz /path/to/file
52
```
53

54
### Print Attribute Value
55

56
Print the value of a specific extended attribute.
57

58
```bash { .api }
59
xattr -p [-slz] attr_name file [file ...]
60
```
61

62
**Parameters:**
63
- `-p`: Print mode - show attribute value
64
- `attr_name`: Name of the attribute to display
65
- `file`: Path to file(s) to examine
66
- `-s`: Act on symbolic links themselves
67
- `-l`: Show in long format with hex dump for binary data
68
- `-z`: Decompress attribute if compressed
69

70
**Usage Examples:**
71

72
```bash
73
# Print specific attribute value
74
xattr -p user.description /path/to/file
75

76
# Print from multiple files
77
xattr -p user.title file1.txt file2.txt
78

79
# Print with hex dump for binary data
80
xattr -pl user.binary_data /path/to/file
81

82
# Print compressed attribute
83
xattr -pz user.compressed_info /path/to/file
84
```
85

86
### Write Attribute Value
87

88
Set the value of an extended attribute.
89

90
```bash { .api }
91
xattr -w [-sz] attr_name attr_value file [file ...]
92
```
93

94
**Parameters:**
95
- `-w`: Write mode - set attribute value
96
- `attr_name`: Name of the attribute to set
97
- `attr_value`: Value to assign (will be encoded as UTF-8 bytes)
98
- `file`: Path to file(s) to modify
99
- `-s`: Act on symbolic links themselves
100
- `-z`: Compress attribute value in zip format
101

102
**Usage Examples:**
103

104
```bash
105
# Set attribute value
106
xattr -w user.description "This is my important file" /path/to/file
107

108
# Set on multiple files
109
xattr -w user.author "John Doe" file1.txt file2.txt
110

111
# Set on symlink itself
112
xattr -ws user.link_type "shortcut" /path/to/symlink  
113

114
# Set compressed attribute
115
xattr -wz user.large_data "Large content that will be compressed" /path/to/file
116
```
117

118
### Delete Attribute
119

120
Remove a specific extended attribute.
121

122
```bash { .api }
123
xattr -d [-s] attr_name file [file ...]
124
```
125

126
**Parameters:**
127
- `-d`: Delete mode - remove attribute
128
- `attr_name`: Name of the attribute to remove
129
- `file`: Path to file(s) to modify
130
- `-s`: Act on symbolic links themselves
131

132
**Usage Examples:**
133

134
```bash
135
# Remove specific attribute
136
xattr -d user.old_description /path/to/file
137

138
# Remove from multiple files
139
xattr -d user.temp_data file1.txt file2.txt
140

141
# Remove from symlink itself
142
xattr -ds user.link_info /path/to/symlink
143
```
144

145
### Clear All Attributes
146

147
Remove all extended attributes from files.
148

149
```bash { .api }
150
xattr -c [-s] file [file ...]
151
```
152

153
**Parameters:**
154
- `-c`: Clear mode - remove all attributes
155
- `file`: Path to file(s) to modify
156
- `-s`: Act on symbolic links themselves
157

158
**Usage Examples:**
159

160
```bash
161
# Clear all attributes from a file
162
xattr -c /path/to/file
163

164
# Clear attributes from multiple files
165
xattr -c file1.txt file2.txt /path/to/dir
166

167
# Clear attributes from symlink itself
168
xattr -cs /path/to/symlink
169
```
170

171
### Help
172

173
Display usage information and available options.
174

175
```bash { .api }
176
xattr -h
177
xattr --help
178
```
179

180
## Complete Workflow Examples
181

182
### File Metadata Management
183

184
```bash
185
# Add metadata to a document
186
xattr -w user.title "Project Proposal" document.pdf
187
xattr -w user.author "Jane Smith" document.pdf  
188
xattr -w user.version "1.0" document.pdf
189
xattr -w user.tags "project,proposal,draft" document.pdf
190

191
# View all metadata
192
xattr -l document.pdf
193

194
# Update specific metadata
195
xattr -w user.version "1.1" document.pdf
196

197
# Check specific attribute
198
xattr -p user.author document.pdf
199

200
# Remove temporary attributes
201
xattr -d user.temp_notes document.pdf
202

203
# Clean up all metadata when done
204
xattr -c document.pdf
205
```
206

207
### Batch Operations
208

209
```bash
210
# Set the same attribute on multiple files
211
xattr -w user.project "WebApp" *.html *.css *.js
212

213
# List attributes for all files in directory
214
xattr /path/to/project/*
215

216
# Remove specific attribute from all project files  
217
xattr -d user.old_version /path/to/project/*
218

219
# View detailed attributes for all files
220
xattr -l /path/to/project/*
221
```
222

223
### Working with Symlinks
224

225
```bash
226
# Create symlink
227
ln -s /original/file /path/to/symlink
228

229
# Set attribute on original file (default)
230
xattr -w user.description "Original file" /path/to/symlink
231

232
# Set attribute on symlink itself
233
xattr -ws user.link_info "Points to original" /path/to/symlink
234

235
# Compare attributes
236
echo "Original file attributes:"
237
xattr -l /original/file
238
echo "Symlink attributes:"  
239
xattr -ls /path/to/symlink
240
```
241

242
## Output Formats
243

244
### Standard List Format
245

246
```bash
247
$ xattr /path/to/file
248
user.description
249
user.title
250
user.version
251
```
252

253
### Long Format (-l)
254

255
```bash
256
$ xattr -l /path/to/file
257
user.description: My important document
258
user.title: Project Proposal
259
user.version: 1.0
260
```
261

262
### Multiple Files
263

264
```bash
265
$ xattr file1.txt file2.txt
266
file1.txt: user.author
267
file1.txt: user.version
268
file2.txt: user.title
269
file2.txt: user.tags
270
```
271

272
### Binary Data Hex Dump
273

274
When attribute values contain binary data or null bytes, the tool automatically switches to hex dump format:
275

276
```bash
277
$ xattr -pl user.binary_data /path/to/file
278
user.binary_data:
279
0000   89 50 4E 47 0D 0A 1A 0A   .PNG....
280
0008   00 00 00 0D 49 48 44 52   ....IHDR
281
```
282

283
## Error Handling
284

285
The command-line tool provides clear error messages for common issues:
286

287
```bash
288
# File not found
289
$ xattr /nonexistent/file
290
No such file: /nonexistent/file
291

292
# Attribute not found  
293
$ xattr -p user.missing /path/to/file
294
No such xattr: user.missing
295

296
# Permission denied
297
$ xattr -w user.test "value" /protected/file
298
Operation not permitted
299

300
# Invalid operation combinations
301
$ xattr -pw user.attr "value" /path/to/file
302
-p not allowed with -w
303
```
304

305
## Platform Notes
306

307
- **Linux**: User attributes require 'user.' namespace prefix (handled automatically)
308
- **macOS**: Supports special attributes like Finder info and resource forks
309
- **All platforms**: Symbolic link handling varies by filesystem support
310

311
## Exit Codes
312

313
- `0`: Success - all operations completed without errors
314
- `1`: Partial failure - some operations failed but others succeeded  
315
- `64`: Usage error - invalid command line arguments