io.github.edithatogo/osf-cli-go

Official

by edithatogo · Go

OSF CLI Go

Read-only MCP tools for authenticated Open Science Framework projects and files.

Read-only tools for accessing authenticated Open Science Framework projects and files.

Topics

cligoopen-science-frameworkosf

README.md5 KBView on GitHub

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

powershell

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:

powershell

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.

powershell

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

For guided token setup:

powershell

osf auth login

Quick Start

powershell

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:

powershell

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.

Install

Configuration

Environment variables

OSF_TOKENsecret

Preferred OSF personal access token.

OSF_USERNAMEsecret

Optional OSF username fallback when OSF_TOKEN is not provided.

OSF_PASSWORDsecret

Optional OSF password fallback when OSF_TOKEN is not provided.

claude_desktop_config.json

{
  "mcpServers": {
    "osf-cli-go": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/edithatogo/osf-cli-go-osf-mcp:0.2.0"
      ],
      "env": {
        "OSF_TOKEN": "<YOUR_OSF_TOKEN>",
        "OSF_USERNAME": "<YOUR_OSF_USERNAME>",
        "OSF_PASSWORD": "<YOUR_OSF_PASSWORD>"
      }
    }
  }
}