0
# Command Line Interface
1

2
Full-featured CLI for OSF operations accessible via the `osf` command. Provides project setup, file listing, downloading, uploading, and URL generation capabilities with support for both public and private projects.
3

4
## Capabilities
5

6
### Project Configuration
7

8
```bash { .api }
9
osf init
10
```
11

12
Set up a `.osfcli.config` file for the current directory. Prompts for username and project ID. Authentication credentials are handled via environment variables.
13

14
Creates configuration file format:
15
```ini
16
[osf]
17
username = your@email.com
18
project = your_project_id
19
```
20

21
Note: Passwords and tokens are not stored in the config file for security. Use environment variables `OSF_PASSWORD` or `OSF_TOKEN` instead.
22

23
### Authentication and Configuration
24

25
Configuration precedence (highest to lowest):
26
1. Command line options (`-u/--username`, `-p/--project`)
27
2. Environment variables (`OSF_USERNAME`, `OSF_PROJECT`, `OSF_PASSWORD`, `OSF_TOKEN`)
28
3. Configuration file (`.osfcli.config`)
29

30
Authentication flow:
31
- Token authentication via `OSF_TOKEN` takes precedence over username/password
32
- If username is provided but no token, password is read from `OSF_PASSWORD` environment variable
33
- If no password environment variable is set, user is prompted for password interactively
34
- Private projects require authentication; public projects can be accessed without credentials
35

36
### File Listing
37

38
```bash { .api }
39
osf list
40
osf ls    # alias
41
```
42

43
List all files from all storage providers for the configured project. Shows file paths only.
44

45
Options:
46
- Requires project configuration or `-p/--project` flag
47
- Requires authentication for private projects
48

49
### Project Cloning
50

51
```bash { .api }
52
osf clone [output_directory]
53
```
54

55
Download all files from all storage providers of the project to a local directory.
56

57
Parameters:
58
- `output_directory` (optional): Target directory for downloaded files. Defaults to current directory.
59

60
Options:
61
- `-U, --update`: Overwrite only if local and remote files differ (based on MD5 checksums)
62

63
Note: Shows progress bars during download operations for large files.
64

65
### Individual File Download
66

67
```bash { .api }
68
osf fetch <remote_path> [local_path]
69
```
70

71
Download a specific file from the project.
72

73
Parameters:
74
- `remote_path` (required): Path to file in remote storage
75
- `local_path` (optional): Local file path. Defaults to remote filename in current directory.
76

77
Options:
78
- `-f, --force`: Force overwriting of local file
79
- `-U, --update`: Overwrite only if local and remote files differ (based on MD5 checksums)
80

81
### File Upload
82

83
```bash { .api }
84
osf upload <source> <destination>
85
```
86

87
Upload a file or directory to the project.
88

89
Parameters:
90
- `source` (required): Local file or directory path
91
- `destination` (required): Remote path in project
92

93
Options:
94
- `-f, --force`: Force overwriting of remote file
95
- `-U, --update`: Overwrite only if local and remote files differ (based on MD5 checksums)
96
- `-r, --recursive`: Recursively upload entire directories
97

98
Note: Creates necessary parent directories automatically. Progress bars shown for large file uploads.
99

100
### File Removal
101

102
```bash { .api }
103
osf remove <target>
104
osf rm <target>    # alias
105
```
106

107
Remove a file from the project's storage.
108

109
Parameters:
110
- `target` (required): Remote file path to remove
111

112
### URL Generation
113

114
```bash { .api }
115
osf geturl <remote_path>
116
```
117

118
Get the web download URL for a specific file in the project.
119

120
Parameters:
121
- `remote_path` (required): Path to file in remote storage
122

123
Returns the public download URL that can be shared or used in browsers.
124

125
## Global Options
126

127
All commands support these global options:
128

129
```bash { .api }
130
osf [global_options] <command> [command_options]
131
```
132

133
Global options:
134
- `-u, --username <username>`: OSF username (overrides config file)
135
- `-p, --project <project_id>`: OSF project ID (overrides config file)
136
- `-h, --help`: Show help message
137
- `-v, --version`: Show version information
138

139
## Authentication
140

141
The CLI supports multiple authentication methods:
142

143
### Environment Variables
144
```bash
145
export OSF_USERNAME="your@email.com"
146
export OSF_PASSWORD="your_password"
147
# OR
148
export OSF_TOKEN="your_personal_access_token"
149

150
osf ls
151
```
152

153
### Configuration File
154
```bash
155
osf init  # Creates .osfcli.config with credentials
156
osf ls
157
```
158

159
### Command Line Arguments
160
```bash
161
osf -u your@email.com -p project_id ls
162
# Password will be prompted if needed
163
```
164

165
## Storage Providers
166

167
Commands work with multiple storage providers. Remote paths can include provider prefixes:
168

169
- `osfstorage/path/file.txt` - OSF Storage (default)
170
- `github/path/file.txt` - GitHub integration
171
- `figshare/path/file.txt` - Figshare integration  
172
- `googledrive/path/file.txt` - Google Drive integration
173
- `owncloud/path/file.txt` - ownCloud integration
174

175
If no provider prefix is specified, `osfstorage` is assumed.
176

177
## Usage Examples
178

179
### Basic Workflow
180

181
```bash
182
# 1. Set up project
183
osf init
184
# Enter username: user@example.com
185
# Enter project ID: 9zpcy
186
# Enter token (optional): your_token_here
187

188
# 2. List project files
189
osf ls
190

191
# 3. Download all files
192
osf clone ./my_project_data
193

194
# 4. Upload new analysis
195
osf upload ./analysis_results.csv data/analysis_results.csv
196

197
# 5. Get shareable URL
198
osf geturl data/analysis_results.csv
199
```
200

201
### Working with Different Storage Providers
202

203
```bash
204
# List files from specific storage
205
osf ls  # Shows all files with storage prefixes
206

207
# Download from GitHub storage
208
osf fetch github/README.md ./local_readme.md
209

210
# Upload to specific storage (if provider accepts uploads)
211
osf upload ./local_file.txt osfstorage/data/file.txt
212
```
213

214
### Advanced File Operations
215

216
```bash
217
# Force overwrite existing files
218
osf upload -f ./updated_data.csv data/dataset.csv
219

220
# Update only if files are different
221
osf upload -U ./maybe_changed.txt documents/report.txt
222

223
# Recursive directory upload
224
osf upload -r ./analysis_results/ results/
225

226
# Sync local changes (update existing, skip unchanged)
227
osf clone -U ./local_project_sync
228
```
229

230
### Batch Operations
231

232
```bash
233
# Download specific files
234
osf fetch data/experiment1.csv
235
osf fetch data/experiment2.csv
236
osf fetch analysis/results.txt
237

238
# Upload multiple files
239
osf upload ./file1.txt data/file1.txt
240
osf upload ./file2.txt data/file2.txt
241

242
# Get URLs for sharing
243
osf geturl data/experiment1.csv
244
osf geturl data/experiment2.csv
245
```
246

247
### Error Handling
248

249
```bash
250
# Check if command succeeded
251
osf ls
252
if [ $? -eq 0 ]; then
253
    echo "Successfully listed files"
254
else
255
    echo "Failed to list files - check authentication and project ID"
256
fi
257

258
# Handle authentication errors
259
osf -u user@example.com ls  # Will prompt for password if needed
260
```
261

262
### Configuration Management
263

264
```bash
265
# Different projects in different directories
266
cd project1/
267
osf init  # Configure for project1
268
osf ls
269

270
cd ../project2/
271
osf init  # Configure for project2
272
osf ls
273

274
# Override config for one-off operations
275
osf -p different_project_id ls
276
```
277

278
## Exit Codes
279

280
The CLI uses standard exit codes:
281
- `0`: Success
282
- `1`: General error (authentication, network, etc.)
283
- `2`: File not found or access denied
284
- Other non-zero: Various error conditions
285

286
These can be used in scripts for error handling and automation.