1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
.\" 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-11" "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
.RS 4
\fBchangelog\fR
.P
\fBhelp\fR
.P
\fBstatus\fR
.P
.RE
.SS Search Commands
.P
.RS 4
\fBsearch\fR <QUERY>...
.P
.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>]
.P
\fBcreate\fR [--input-file <PATH>]
.P
\fBupdate\fR <SPECIFIER> [<FIELD>=<VALUE> ...] [--input-file <PATH>]
.P
\fBdelete\fR <SPECIFIER>
.P
\fBedit\fR <SPECIFIER>
.P
\fBdownload\fR <SPECIFIER>
.P
\fBhistory\fR <SPECIFIER>
.P
.RE
.SS Batch Commands
.P
.RS 4
\fBbatch update\fR [<FIELD>=<VALUE> ...]
.P
\fBbatch create\fR
.P
\fBbatch download\fR [--jobs=N]
.P
.RE
.SS Editgroup Commands
.P
.RS 4
\fBeditgroups list\fR
.P
\fBeditgroups reviewable\fR
.P
\fBeditgroups submit\fR <EDITGROUP-ID>
.P
\fBeditgroups unsubmit\fR <EDITGROUP-ID>
.P
\fBeditgroups accept\fR <EDITGROUP-ID>
.P
.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
.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:
.P
.RS 4
fatcat-cli search releases journal:"first monday" --entity-json --expand files | fatcat-cli batch download --limit 100
.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>
.RE
|
