osfcli

package module

v0.2.0 Latest Latest Go to latest Published: May 18, 2026 License: Apache-2.0 Imports: 0 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/edithatogo/osf-cli-go

Links

Open Source Insights

README ¶

osf-cli-go

A Go command-line client for the Open Science Framework (OSF).

Features

osf auth whoami — Identify the authenticated OSF account
osf auth login — Guided personal-access-token bootstrap for username/password users
osf projects list|get — List and inspect projects
osf components list — List project components
osf files list|download|upload|mkdir|rm — Browse, download, upload, create folders, and delete OSF Storage files
osf search and osf preprints list — Search OSF and list preprints
osf registrations create — Create draft registrations for an existing node
osf export — Export a node snapshot as JSON or a summary table
osf-mcp — Stdio MCP server exposing read-only OSF tools for agent clients
osf completion bash|zsh|fish|powershell — Shell completion scripts
JSON and human-readable output modes
Safe, atomic file downloads with conflict policy (fail/skip/overwrite)

Install

Requirements:

Go 1.26 or newer

go install github.com/edithatogo/osf-cli-go/cmd/osf@latest
go install github.com/edithatogo/osf-cli-go/cmd/osf-mcp@latest

Or from a local checkout:

go build -o bin\osf.exe ./cmd/osf
go build -o bin\osf-mcp.exe ./cmd/osf-mcp
.\scripts\build.ps1

Authentication

Set OSF_TOKEN in your shell session. Do not commit the token or write it into project files. OSF_USERNAME and OSF_PASSWORD are supported as an opt-in fallback credential source, but personal access tokens remain preferred for automation and for accounts using SSO or two-factor authentication.

$env:OSF_TOKEN = '<your-token>'

For guided token setup:

osf auth login

Quick Start

osf --help
osf auth whoami
osf projects list
osf projects get https://osf.io/abc12/
osf components list abc12
osf files list abc12
osf files download --file <file-id> ./output/
osf files download --tree abc12 ./output/
osf files upload --node abc12 ./report.pdf
osf search "open science"
osf preprints list
osf registrations create abc12 --schema <schema-id> --title "Analysis plan"
osf export abc12 --json

MCP Server

osf-mcp runs a stdio MCP server with read-only tools: osf_whoami, osf_projects_list, osf_project_get, osf_components_list, osf_files_list, and osf_contributors_list.

Local development configs are included for GitHub Copilot, VS Code, Claude, Codex, Gemini CLI, and Qwen Code. Public registry metadata is in server.json and registry/.

Output Modes

All commands support --output table|json and --json shorthand:

osf projects list --json
osf auth whoami --output json

Project Status

The CLI is offline-tested for read-only operations, file downloads, WaterButler write primitives, search, preprint listing, draft registration creation, project create/update/delete operations, and node export. All Conductor tracks are reconciled against their per-track plans with closeout review evidence; live OSF validation remains opt-in because it requires credentials and network access.

Documentation

License

Apache 2.0 — see LICENSE.

Citation

If you use this software in your research, please cite it using the metadata in CITATION.cff.

Documentation ¶

Overview ¶

osf-cli-go is a command-line client for the Open Science Framework (OSF).

Overview ¶

osf-cli-go provides read-only access to OSF projects, components, and files through a Cobra-based CLI. It supports both JSON and human-readable output.

Commands ¶

osf auth whoami                  — Show the authenticated OSF account
osf projects list                — List accessible projects
osf projects get <guid-or-url>   — Show one project
osf components list <project>    — List child components
osf files list <node>            — List OSF Storage files
osf files download --file <id>   — Download a single file
             --tree <node> <dest> — Download a folder tree
osf completion bash|zsh|fish|powershell — Shell completions

Authentication ¶

Set the OSF_TOKEN environment variable to a valid OSF personal access token. Without a token, only public node metadata and public storage files are accessible.

Package Layout ¶

cmd/osf/            — CLI entry point
internal/auth/      — Token loading and redaction
internal/cli/       — Cobra command definitions and routing
internal/download/  — Safe file download with conflict handling
internal/osfapi/    — OSF API v2 JSON:API client
internal/output/    — JSON and table output helpers

Source Files ¶

View all Source files

doc.go

Directories ¶

Path	Synopsis
cmd
osf command
osf-mcp command
internal
auth Package auth loads OSF credentials from caller-provided sources and redacts secrets from user-visible errors and logs.	Package auth loads OSF credentials from caller-provided sources and redacts secrets from user-visible errors and logs.
cli Package cli builds and executes the osf command tree.	Package cli builds and executes the osf command tree.
download Package download provides safe local file writes for OSF downloads, including conflict policies, path traversal protection, and folder-tree manifests.	Package download provides safe local file writes for OSF downloads, including conflict policies, path traversal protection, and folder-tree manifests.
mcpserver
osfapi Package osfapi implements the OSF API v2 HTTP client used by the CLI.	Package osfapi implements the OSF API v2 HTTP client used by the CLI.
output Package output renders command results as stable JSON or aligned text tables.	Package output renders command results as stable JSON or aligned text tables.
tools
checkreviews command
checkstubs command
livevalidation command

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL