start re-writing README

1 files changed, 95 insertions, 8 deletions

diff --git a/README.md b/README.md
index a5c1f49..48eb200 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,100 @@
 
-**fatcat-cli**: command-line utility for interacting with https://fatcat.wiki API
+<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
+====================================================
 
-## History / Status
+**DISCLAIMER:** this tool is still under development. The interface (arguments,
+flags) and default behaviors are not yet stable.
 
-This side-project is currently a work-in-progress.
+## Install
 
-Eventually intend to merge this repo back in to the main fatcat git repo, but
-it currently uses a newer version of the openapi code generator tool. Updating
-the fatcat API server rust code (`fatcatd`) will take a good deal of
-refactoring, and this version of the codegen tool isn't even stable at the time
-this fork started.
+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.