Command Line Interface

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.

Capabilities

Project Configuration

osf init

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

Creates configuration file format:

[osf]
username = your@email.com
project = your_project_id

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

Authentication and Configuration

Configuration precedence (highest to lowest):

1. Command line options (-u/--username, -p/--project)
2. Environment variables (OSF_USERNAME, OSF_PROJECT, OSF_PASSWORD, OSF_TOKEN)
3. Configuration file (.osfcli.config)

Authentication flow:

• Token authentication via OSF_TOKEN takes precedence over username/password
• If username is provided but no token, password is read from OSF_PASSWORD environment variable
• If no password environment variable is set, user is prompted for password interactively
• Private projects require authentication; public projects can be accessed without credentials

File Listing

osf list
osf ls    # alias

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

Options:

• Requires project configuration or -p/--project flag
• Requires authentication for private projects

Project Cloning

osf clone [output_directory]

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

Parameters:

• output_directory (optional): Target directory for downloaded files. Defaults to current directory.

Options:

• -U, --update: Overwrite only if local and remote files differ (based on MD5 checksums)

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

Individual File Download

osf fetch <remote_path> [local_path]

Download a specific file from the project.

Parameters:

• remote_path (required): Path to file in remote storage
• local_path (optional): Local file path. Defaults to remote filename in current directory.

Options:

• -f, --force: Force overwriting of local file
• -U, --update: Overwrite only if local and remote files differ (based on MD5 checksums)

File Upload

osf upload <source> <destination>

Upload a file or directory to the project.

Parameters:

• source (required): Local file or directory path
• destination (required): Remote path in project

Options:

• -f, --force: Force overwriting of remote file
• -U, --update: Overwrite only if local and remote files differ (based on MD5 checksums)
• -r, --recursive: Recursively upload entire directories

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

File Removal

osf remove <target>
osf rm <target>    # alias

Remove a file from the project's storage.

Parameters:

• target (required): Remote file path to remove

URL Generation

osf geturl <remote_path>

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

Parameters:

• remote_path (required): Path to file in remote storage

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

Global Options

All commands support these global options:

osf [global_options] <command> [command_options]

Global options:

• -u, --username <username>: OSF username (overrides config file)
• -p, --project <project_id>: OSF project ID (overrides config file)
• -h, --help: Show help message
• -v, --version: Show version information

Authentication

The CLI supports multiple authentication methods:

Environment Variables

export OSF_USERNAME="your@email.com"
export OSF_PASSWORD="your_password"
# OR
export OSF_TOKEN="your_personal_access_token"

osf ls

Configuration File

osf init  # Creates .osfcli.config with credentials
osf ls

Command Line Arguments

osf -u your@email.com -p project_id ls
# Password will be prompted if needed

Storage Providers

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

• osfstorage/path/file.txt - OSF Storage (default)
• github/path/file.txt - GitHub integration
• figshare/path/file.txt - Figshare integration
• googledrive/path/file.txt - Google Drive integration
• owncloud/path/file.txt - ownCloud integration

If no provider prefix is specified, osfstorage is assumed.

Usage Examples

Basic Workflow

# 1. Set up project
osf init
# Enter username: user@example.com
# Enter project ID: 9zpcy
# Enter token (optional): your_token_here

# 2. List project files
osf ls

# 3. Download all files
osf clone ./my_project_data

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

# 5. Get shareable URL
osf geturl data/analysis_results.csv

Working with Different Storage Providers

# List files from specific storage
osf ls  # Shows all files with storage prefixes

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

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

Advanced File Operations

# Force overwrite existing files
osf upload -f ./updated_data.csv data/dataset.csv

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

# Recursive directory upload
osf upload -r ./analysis_results/ results/

# Sync local changes (update existing, skip unchanged)
osf clone -U ./local_project_sync

Batch Operations

# Download specific files
osf fetch data/experiment1.csv
osf fetch data/experiment2.csv
osf fetch analysis/results.txt

# Upload multiple files
osf upload ./file1.txt data/file1.txt
osf upload ./file2.txt data/file2.txt

# Get URLs for sharing
osf geturl data/experiment1.csv
osf geturl data/experiment2.csv

Error Handling

# Check if command succeeded
osf ls
if [ $? -eq 0 ]; then
    echo "Successfully listed files"
else
    echo "Failed to list files - check authentication and project ID"
fi

# Handle authentication errors
osf -u user@example.com ls  # Will prompt for password if needed

Configuration Management

# Different projects in different directories
cd project1/
osf init  # Configure for project1
osf ls

cd ../project2/
osf init  # Configure for project2
osf ls

# Override config for one-off operations
osf -p different_project_id ls

Exit Codes

The CLI uses standard exit codes:

• 0: Success
• 1: General error (authentication, network, etc.)
• 2: File not found or access denied
• Other non-zero: Various error conditions

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