aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
blob: 48eb200b144be1695bf0d73579bafa61c404a06e (plain)
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

<div align="center">
<!-- https://www.flickr.com/photos/threecheersformcr_xo/5340309206/ -->
<!-- TODO: move to an archive.org item... or just include in this repo -->
<img src="http://static.bnewbold.net/tmp/keyboard-cat-flickr-threecheersformcr_xo.jpg">
</div>

`fatcat-cli`: api.fatcat.wiki command-line utility
====================================================

**DISCLAIMER:** this tool is still under development. The interface (arguments,
flags) and default behaviors are not yet stable.

## Install

Debian/Ubuntu Linux users can install bare `.deb` packages. Download the most
recent from <http://archive.org/download/ia-fatcat-cli-bin>, then install with:

    sudo apt install ./fatcat-cli-*.deb

<!--
MacOS Homebrew users with Intel CPUs, can install using a "tap":

    brew install bnewbold/fatcat/fatcat-cli
-->

<!--
Users on all other platforms can use the Rust `cargo` tool to build and install
the utility for their user. Unfortunately this will not include the manual
("man page") or shell completions:

    cargo install fatcat-cli
-->

## Quickstart

Query the catalog:

    fatcat search releases "metadata author:phillips"

Fetch metadata for a specific work:

    fatcat get doi:10.1002/spe.659

Download 100 papers from a specific journal, as PDF:

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

### Authentication

To propose changes to the catalog, you need a <https://fatcat.wiki> account.
You can create one quickly by logging in with an existing Internet Archive,
ORCiD, Wikipedia, or Gitlab account. Create a new API token from the [account
page](https://fatcat.wiki/auth/account), and set this token (a long sequence of
characters) as an environment variable in your shell:

    export FATCAT_API_AUTH_TOKEN=...

You could put this in a secrets/password manager so you don't lose it. Or,
depending on your setup, in a`~/.profile`. The tool does not (yet)
automatically load "dotenv" (`./.env`) files, but you might be using a
project-management tool which does so already.

You can check the status of your authentication and connection to the server
with:

    fatcat status

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

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

    fatcat get release_hsmo6p4smrganpb3fndaj2lon4 --json > release_hsmo6p4smrganpb3fndaj2lon4.json

    # whatever editor you prefer
    emacs release_hsmo6p4smrganpb3fndaj2lon4

    fatcat update release_hsmo6p4smrganpb3fndaj2lon4 < release_hsmo6p4smrganpb3fndaj2lon4.
json

Or, with a single command:

    fatcat edit release_hsmo6p4smrganpb3fndaj2lon4 --toml

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

    fatcat editgroups list
    fatcat editgroups submit editgroup_...

## Thanks!

The "keyboard cat" photo at the top of this README is by Cassandra Leigh Gotto ([threecheersformcr_xo](https://www.flickr.com/photos/threecheersformcr_xo/5340309206/)) and shared under the [CC-BY-NC](https://creativecommons.org/licenses/by-nc/2.0/) license.