path: root/extra/fatcat-cli.1

.\" Generated by scdoc 1.9.0
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "fatcat-cli" "1" "2021-02-15" "Fatcat API Tool Manual Page"
.P
.SH NAME
.P
fatcat-cli - client for fatcat.wiki API
.P
.SH SYNOPSIS
.P
fatcat-cli [OPTIONS] <COMMAND> <ARGS>
.P
.SH DESCRIPTION
.P
NOTE: this manual page is a work-in-progress
.P
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.
.P
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).
.P
.SH COMMANDS
.P
.SS Search Commands
.P
.RS 4
\fBsearch\fR <ENTITY-TYPE> <QUERY>...
.RS 4
Query the search index for entities of a specified type. Currently `release`, `container`, and `file` indexes are searchable. By default prints a table with a subset of metadata, but `--index-json` will output the search engine JSON document, or `--entity-json` will do an API fetch for each result and print the full entity JSON.
.P
.RE
.RE
.SS Single Entity Commands
.P
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, 
.P
.RS 4
\fBget\fR <SPECIFIER> [--expand <FIELDS>] [--hide <FIELDS>] [--json/--toml]
.RS 4
Simply fetches the specified entity or other object from the API and prints to stdout. Currently pretty-prints JSON, but this behavior may change.
.P
.RE
\fBcreate\fR [-i/--input-file <PATH>] [-e/--editgroup-id <id>]
.RS 4
Reads entity from file (or stdin), and adds to the editgroup specified by argument or environment variable.
.P
.RE
\fBupdate\fR <SPECIFIER> [<FIELD>=<VALUE> ...] [-i/--input-file <PATH>] [-e/--editgroup-id <id>]
.RS 4
Can operate in two ways. If no input file is given, will fetch the specified entity, apply the given mutations (updating field values), and push the update to the specified editgroup. If an input file is given, that will be used instead of fetching from the API.
If there is an edit to the same entity in the current editgroup, will delete the current edit ("update the edit"). Note this behavior could result in loss of the current edit if there is a problem updating.
.P
.RE
\fBdelete\fR <SPECIFIER> [-e/--editgroup-id <id>]
.RS 4
Deletes the specified entity, as part of the specified editgroup.
.P
.RE
\fBedit\fR <SPECIFIER> [-e/--editgroup-id <id>] [--toml] [--editing-command <EDITOR>]
.RS 4
Helper command to edit the given entity using a local text editor. Fetches the entity, opens `$EDITOR` to modify it, then pushes the saved version as part of the given editgroup.
.P
.RE
\fBdownload\fR <SPECIFIER> [-o/--output-dir <path>]
.RS 4
Downloads a publicly accessibly full-text version of the given entity to disk, if one exists. Currently works with file and release entities. Most files are PDF.
.P
.RE
\fBhistory\fR <SPECIFIER> [-n/--limit <count>] [--json]
.RS 4
Displays the (accepted) edit history for the given entity.
.P
.RE
.RE
.SS Batch Commands
.P
Batch editing commands will operate on a stream of entities by automatically create new editgroups of a fixed batch size. Please be careful with these commands! Start small, and test against the QA API environment (api.qa.fatcat.wiki).
.P
.RS 4
\fBbatch update\fR [<FIELD>=<VALUE> ...]
.RS 4
Same as the `update` command, but operates on a stream of JSON entities (one per line).
.P
.RE
\fBbatch create\fR
.RS 4
Same as the `create` command, but operates on a stream of JSON entities (one per line).
.P
.RE
\fBbatch download\fR [-j/--jobs=N]
.RS 4
Same as `download`, but operates on a stream of entities. A tab-separated log of {entity, status, path} will be printed to stdout. The jobs argument can be used to download multiple files in parallel, up to a reasonable limit.
.P
.RE
.RE
.SS Editgroup Commands
.P
.RS 4
\fBeditgroups list\fR [-n/--limit <count>] [-e/--editor-id <ident>] [--json]
.RS 4
Prints a simple table of editgroups created by the current user (requires authentication).
.P
.RE
\fBeditgroups reviewable\fR [--json]
.RS 4
Prints a table of "submitted" but not "accepted" editgroups, from all editors, which need review
.P
.RE
\fBeditgroups submit\fR <EDITGROUP-ID>
.RS 4
Submit the given editgroup for review (requires authentication)
.P
.RE
\fBeditgroups unsubmit\fR <EDITGROUP-ID>
.RS 4
Withdraws submission for review, so the editgroup can be further edited (requires authentication)
.P
.RE
\fBeditgroups accept\fR <EDITGROUP-ID>
.RS 4
Accepts the editgroup changes into the catalog (requires authentication and admin permissions)
.P
.P
.RE
.RE
.SS Other Commands
.P
.RS 4
\fBchangelog\fR [--json]
.RS 4
Prints a table of recent changelog entries (accepted editgroups)
.P
.RE
\fBstatus\fR [--json]
.RS 4
Summarizes connection and authentication to the API server. Useful for debugging
.P
.RE
.RE
.SH OPTIONS
.P
\fB-h, --help\fR
.RS 4
Prints help information
.P
.RE
\fB-V, --version\fR
.RS 4
Prints version information
.P
.RE
\fB-v, --verbose\fR
.RS 4
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.
.P
.RE
\fB--api-host <api-host>\fR [env: FATCAT_API_HOST] [default: https://api.fatcat.wiki]
.P
\fB--api-token <api-token>\fR [env: FATCAT_API_AUTH_TOKEN]
.P
\fB--search-host <search-host>\fR [env: FATCAT_SEARCH_HOST] [default: https://search.fatcat.wiki]
.P
.SS Search Options
.P
\fB-count\fR
.RS 4
Just print the number of search results matching the query, instead of displaying the results themselves.
.P
.RE
\fB-n, --limit <count>\fR
.RS 4
Maximum number of search rows to be printed. Set to 0 to print all results (this is not the default behavior).
.P
.RE
\fB--expand <fields>\fR
.RS 4
When output is expanded entity JSON objects (`--entity-json`), this argument will be forwarded as the 'expand' paramter in API fetches. Multiple expansions can be separated by commas, with no space. For example, `--expand files,filesets`.
.P
.RE
\fB--hide <fields>\fR
.RS 4
Same as `--expand`, but for hiding fields/sub-entities.
.P
.RE
\fB--expand-json\fR
.RS 4
For each search result row, do an API fetch for the entity and print the entity as JSON. Because there is an API call for each row, this is much slower than the default table output, or the `--index-json` output.
.P
.RE
\fB--index-json\fR
.RS 4
For each search result row, print the search engine (Elasticsearch) indexed "document", as JSON.
.P
.RE
.SS Batch Options
.P
\fB-i, --input-file\fR
.RS 4
JSON lines file to read entities from. Defaults to stdin; "-" can also be passed to explicitly use stdin.
.P
.RE
\fB-n, --limit <count>\fR
.RS 4
Only operate on the given number of entities. By default, no limit. Good to use defensively to prevent large accidental edits.
.P
.RE
\fB--batch-size <count>\fR
.RS 4
For editing batch commands, how many entity edits should be bundled into each editgroup.
.P
.RE
\fB--auto-accept\fR
.RS 4
For editing batch commands, this argument will result in each editgroup being accepted without review. Requires admin permissions.
.P
.RE
.SH EDITING
.P
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.
.P
Create a new editgroup:
.P
.RS 4
fatcat-cli editgroups create --description "demonstration edit"
.P
# grab the editgroup_id from the output, eg "uy7qzonuwbcitdhhyuk5vjtsdy"
.P
.RE
Individual entities can be edited from the convenience of your text editor, in either JSON or TOML format:
.P
.RS 4
fatcat-cli get release_hsmo6p4smrganpb3fndaj2lon4 --json > release_hsmo6p4smrganpb3fndaj2lon4.json
.P
# whatever editor you prefer
$EDITOR release_hsmo6p4smrganpb3fndaj2lon4
.P
fatcat-cli update release_hsmo6p4smrganpb3fndaj2lon4 -e <editgroup_id> < release_hsmo6p4smrganpb3fndaj2lon4.json
.P
.RE
Or, with a single command:
.P
.RS 4
fatcat-cli edit release_hsmo6p4smrganpb3fndaj2lon4 --toml -e <editgroup_id>
.P
.RE
To check in on the status of recent editgroups, or to "submit" them for review:
.P
.RS 4
fatcat-cli editgroups list
fatcat-cli editgroups submit <editgroup_id>
.P
.P
.RE
.SH EXAMPLES
.P
Query the catalog:
.P
.RS 4
fatcat-cli search releases author:phillips metadata year:2014
.P
.RE
Fetch metadata for a specific work:
.P
.RS 4
fatcat-cli get doi:10.1002/spe.659
.P
.RE
Download 100 papers from a specific journal, as PDF, to current folder:
.P
.RS 4
fatcat-cli search releases journal:"first monday" --entity-json --expand files -n0 | fatcat-cli batch download --limit 100
.RE