osfcli

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 15, 2026 License: Apache-2.0 Imports: 0 Imported by: 0

README

osf-cli-go

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

CI Lint Security Go Reference License Go Version Release OSF CLI Go MCP server

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, osf search --bibtex, osf preprints list|search, and osf resolve — Search/export OSF literature metadata, discover preprints, and resolve OSF DOI destinations
  • osf registrations create — Create draft registrations for an existing node
  • osf export — Export a node snapshot as JSON or a summary table
  • osf validate — Check OSF node metadata with deterministic research-output or preregistration profiles
  • 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 search "open science" --bibtex
osf preprints list
osf preprints search "open science" --provider osf
osf resolve 10.1234/example
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, osf_contributors_list, osf_search, osf_preprints_list, osf_preprints_search, and osf_doi_resolve.

The parity discovery tools are bounded and deterministic: osf_search requires a non-empty query and accepts a limit from 1 to 100, while osf_preprints_list accepts an optional provider and the same bounded limit. osf_preprints_search requires a title query, accepts an optional provider, and returns publication date, published state, DOI, and OSF HTML URL with a limit from 1 to 100. These tools return structured JSON through the MCP server and never perform writes.

OSF search results include stable IDs, title, abstract, keywords, year, and URL. Use osf search <query> --bibtex to emit deterministic BibTeX records for literature-review workflows. The command does not resolve contributor names or download PDFs automatically.

For DataLad workflows, OSF CLI Go provides the general-purpose OSF API and safe file primitives used around a dataset, including osf export and osf files download --tree. It does not install or configure DataLad, Git remotes, or git-annex special remotes; those integrations remain a separately scoped interoperability boundary.

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/.

Other maintained servers in the same Glama portfolio:

  • FYI MCP for freedom-of-information request workflows.
  • Healthpoint MCP for licensed health-service directory data.
  • SourceRight for reference and citation verification.

Related OSF ecosystem servers:

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

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.
buildinfo
Package buildinfo resolves the version embedded in a Go binary.
 Package buildinfo resolves the version embedded in a Go binary.
cli
Package cli builds and executes the osf command tree.
 Package cli builds and executes the osf command tree.
crossprovider
Package crossprovider models explicit, provenance-preserving transfers between OSF and Zenodo without implying mirroring or publication.
 Package crossprovider models explicit, provenance-preserving transfers between OSF and Zenodo without implying mirroring or publication.
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
observability
Package observability defines the versioned, redacted operational event contract shared by the CLI, API client, transfer code, and MCP server.
 Package observability defines the versioned, redacted operational event contract shared by the CLI, API client, transfer code, and MCP server.
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.
repository
Package repository defines provider-qualified research repository contracts.
 Package repository defines provider-qualified research repository contracts.
repository/conformancetest
Package conformancetest provides reusable repository contract assertions.
 Package conformancetest provides reusable repository contract assertions.
zenodoapi
Package zenodoapi implements the reviewed read-only Zenodo REST adapter.
 Package zenodoapi implements the reviewed read-only Zenodo REST adapter.
zenodoid
Package zenodoid parses provider-qualified and canonical Zenodo identities.
 Package zenodoid parses provider-qualified and canonical Zenodo identities.
zenodooai
Package zenodooai implements bounded, read-only Zenodo OAI-PMH harvesting.
 Package zenodooai implements bounded, read-only Zenodo OAI-PMH harvesting.
zenodopublish
Package zenodopublish models and executes explicitly authorized Zenodo sandbox publication lifecycle actions.
 Package zenodopublish models and executes explicitly authorized Zenodo sandbox publication lifecycle actions.
zenodotransfer
Package zenodotransfer implements authenticated, sandbox-only Zenodo draft file transfers.
 Package zenodotransfer implements authenticated, sandbox-only Zenodo draft file transfers.
tools
checkapischema command
Command checkapischema validates the pinned official OSF API schema manifest.
 Command checkapischema validates the pinned official OSF API schema manifest.
checkfeaturematrix command
Command checkfeaturematrix validates and renders the canonical feature matrix.
 Command checkfeaturematrix validates and renders the canonical feature matrix.
checkmcpquality command
Command checkmcpquality evaluates the offline MCP quality and compatibility contract.
 Command checkmcpquality evaluates the offline MCP quality and compatibility contract.
checkproviderrelease command
Command checkproviderrelease validates dated, digest-bound provider claims.
 Command checkproviderrelease validates dated, digest-bound provider claims.
checkregistries command
checkreleasecontract command
Command checkreleasecontract validates the repository's release-readiness contract.
 Command checkreleasecontract validates the repository's release-readiness contract.
checkreviews command
checkstubs command
checksums command
Command checksums writes SHA-256 checksums for files in a directory.
 Command checksums writes SHA-256 checksums for files in a directory.
checkzenodoapi command
Command checkzenodoapi validates the pinned Zenodo API capability snapshot.
 Command checkzenodoapi validates the pinned Zenodo API capability snapshot.
crossprovidervalidation command
Command crossprovidervalidation proves an OSF-qualified snapshot can be copied to and compensated from an unpublished Zenodo sandbox draft.
 Command crossprovidervalidation proves an OSF-qualified snapshot can be copied to and compensated from an unpublished Zenodo sandbox draft.
livevalidation command
zenodopublicationvalidation command
Command zenodopublicationvalidation records an offline plan or runs the explicitly opted-in Zenodo sandbox publication lifecycle proof.
 Command zenodopublicationvalidation records an offline plan or runs the explicitly opted-in Zenodo sandbox publication lifecycle proof.
zenodosandboxvalidation command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.