fatcat-cli(1) "Fatcat API Tool Manual Page"

# NAME

fatcat-cli - client for fatcat.wiki API

# SYNOPSIS

fatcat-cli [OPTIONS] <COMMAND> <ARGS>

# DESCRIPTION

NOTE: this manual page is a work-in-progress

This is simple command-line interface to the fatcat catalog API. Fatcat (https://fatcat.wiki) is an open bibliographic catalog of scholarly works, with a focus on access and preservation.

Many commands will work out-of-the-box, but all editing actions require authentication. Create an account on https://fatcat.wiki, then generate an API token (a long string of random characters) from the account page, and export to your shell environment (read below for the env variable to use).

# COMMANDS

	*changelog*

	*help*

	*status*

## Search Commands

	*search* <QUERY>...

## Single Entity Commands

Most commands for interacting with individual catalog entities take a "specifier" which imples an entity type. These can be fatcat-specific "idents", which are an entity type followed by an underscore, then 26 character hash, such as "release_hsmo6p4smrganpb3fndaj2lon4". Or they can be an external identifier type, followed by a colon and the identifier, 

	*get* <SPECIFIER> [--expand <FIELDS>] [--hide <FIELDS>]

	*create* [--input-file <PATH>]

	*update* <SPECIFIER> [<FIELD>=<VALUE> ...] [--input-file <PATH>]

	*delete* <SPECIFIER>

	*edit* <SPECIFIER>

	*download* <SPECIFIER>

	*history* <SPECIFIER>

## Batch Commands

	*batch update* [<FIELD>=<VALUE> ...]

	*batch create*

	*batch download* [--jobs=N]

## Editgroup Commands

	*editgroups list*

	*editgroups reviewable*

	*editgroups submit* <EDITGROUP-ID>

	*editgroups unsubmit* <EDITGROUP-ID>

	*editgroups accept* <EDITGROUP-ID>

# OPTIONS

*-h, --help*
	Prints help information

*-V, --version*
	Prints version information

*-v, --verbose*
	Pass many times for more log output
	By default, it'll only report errors. Passing `-v` one time also prints warnings, `-vv` enables info logging, `-vvv` debug, and `-vvvv` trace.

*--api-host <api-host>* [env: FATCAT_API_HOST] [default: https://api.fatcat.wiki]

*--api-token <api-token>* [env: FATCAT_API_AUTH_TOKEN]

*--search-host <search-host>* [env: FATCAT_SEARCH_HOST] [default: https://search.fatcat.wiki]

# EXAMPLES

Query the catalog:

	fatcat-cli search releases author:phillips metadata year:2014

Fetch metadata for a specific work:

	fatcat-cli get doi:10.1002/spe.659

Download 100 papers from a specific journal, as PDF:

	fatcat-cli search releases journal:"first monday" --entity-json --expand files | fatcat-cli batch download --limit 100

# EDITING

Every change to the catalog (an "edit") is made as part of an "editgroup". In some cases the CLI tool with create or guess what the current editgroup you are working on is, but you can also create them explicitly and pass the editgroup identifier on every subsequent edit. It is best to combine small groups of related changes into the same editgroup (so they can be reviewed together), but to split up larger batches into editgroups of 50-100 changes at a time.

Create a new editgroup:

	fatcat-cli editgroups create --description "demonstration edit"

	# grab the editgroup_id from the output, eg "uy7qzonuwbcitdhhyuk5vjtsdy"

Individual entities can be edited from the convenience of your text editor, in either JSON or TOML format:

	fatcat-cli get release_hsmo6p4smrganpb3fndaj2lon4 --json > release_hsmo6p4smrganpb3fndaj2lon4.json

	# whatever editor you prefer
	$EDITOR release_hsmo6p4smrganpb3fndaj2lon4

	fatcat-cli update release_hsmo6p4smrganpb3fndaj2lon4 -e <editgroup_id> < release_hsmo6p4smrganpb3fndaj2lon4.json

Or, with a single command:

	fatcat-cli edit release_hsmo6p4smrganpb3fndaj2lon4 --toml -e <editgroup_id>

To check in on the status of recent editgroups, or to "submit" them for review:

	fatcat-cli editgroups list
	fatcat-cli editgroups submit <editgroup_id>