diff --git a/GUIDE.md b/GUIDE.md index 864ae45..24f5e26 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -1,143 +1,148 @@ # Write.as CLI User Guide The Write.as Command-Line Interface (CLI) is a cross-platform tool for publishing text to [Write.as](https://write.as) and its other sites, like [Paste.as](https://paste.as). It is designed to be simple, scriptable, do one job (publishing) well, and work as you'd expect with other command-line tools. Write.as is a text-publishing service that protects your privacy. There's no sign up required to publish, but if you do sign up, you can access posts across devices and compile collections of them in what most people would call a "blog". ## Uses These are a few common uses for `writeas`. If you get stuck or want to know more, run `writeas [command] --help`. If you still have questions, [ask us](https://write.as/contact). ### Overview ``` writeas [global options] command [command options] [arguments...] COMMANDS: post Alias for default action: create post from stdin new Compose a new post from the command-line and publish publish Publish a file to Write.as delete Delete a post update Update (overwrite) a post get Read a raw post add Add an existing post locally posts List all of your posts claim Claim local unsynced posts blogs List blogs + claim Claim local unsynced posts auth Authenticate with Write.as logout Log out of Write.as help, h Shows a list of commands or help for one command GLOBAL OPTIONS: - -c value, -b value Optional blog to post to - --tor, -t Perform action on Tor hidden service - --tor-port value Use a different port to connect to Tor (default: 9150) - --code Specifies this post is code - --md Returns post URL with Markdown enabled - --verbose, -v Make the operation more talkative - --font value Sets post font to given value (default: "mono") - --lang value Sets post language to given ISO 639-1 language code - --user-agent value Sets the User-Agent for API requests - --help, -h show help - --version, -V print the version + -c value, -b value Optional blog to post to + --tor, -t Perform action on Tor hidden service + --tor-port value Use a different port to connect to Tor (default: 9150) + --code Specifies this post is code + --md Returns post URL with Markdown enabled + --verbose, -v Make the operation more talkative + --font value Sets post font to given value (default: "mono") + --lang value Sets post language to given ISO 639-1 language code + --user-agent value Sets the User-Agent for API requests + --host value, -H value Operate against a custom hostname + --user value, -u value Use authenticated user, other than default + --help, -h show help + --version, -V print the version ``` +> Note: the host and user flags are only available in `wf` the community edition + #### Share something By default, `writeas` creates a post with a `monospace` typeface that doesn't word wrap (scrolls horizontally). It will return a single line with a URL, and automatically copy that URL to the clipboard: ```bash $ echo "Hello world!" | writeas https://write.as/aaaazzzzzzzza ``` This is generally more useful for posting terminal output or code, like so (the `--code` flag turns on syntax highlighting): macOS / Linux: `cat writeas/cli.go | writeas --code` Windows: `type writeas/cli.go | writeas.exe --code` #### Output a post This outputs any Write.as post with the given ID. ```bash $ writeas get aaaazzzzzzzza Hello world! ``` #### Authenticate This will authenticate with write.as and store the user access token locally, until you explicitly logout. ```bash $ writeas auth username Password: ************ ``` #### List all blogs This will output a list of the authenticated user's blogs. ```bash $ writeas blogs Alias Title user An Example Blog dev My Dev Log ``` #### List all published posts This lists all posts you've published from your device, as well as any published by the authenticated user. Pass the `--url` flag to show the list with full post URLs, and the `--md` flag to return URLs with Markdown enabled. ```bash $ writeas posts Local ID Token unsynced aaaazzzzzzzza dhuieoj23894jhf984hdfs9834hdf84j Account ID Title synced mmmmmmmm33333333 This is a post ``` #### Delete a post This permanently deletes a post you own. ```bash $ writeas delete aaaazzzzzzzza ``` #### Update a post This completely overwrites an existing post you own. ```bash $ echo "See you later!" | writeas update aaaazzzzzzzza ``` #### Claim a post This moves an unsynced local post to a draft on your account. You will need to authenticate first. ```bash $ writeas claim aaaazzzzzzzza ``` ### Composing posts If you simply have a penchant for never leaving your keyboard, `writeas` is great for composing new posts from the command-line. Just use the `new` subcommand. `writeas new` will open your favorite command-line editor, as specified by your `WRITEAS_EDITOR` or `EDITOR` environment variables (in that order), falling back to `vim` on OS X / *nix. Customize your post's appearance with the `--font` flag: | Argument | Appearance (Typeface) | Word Wrap? | | -------- | --------------------- | ---------- | | `sans` | Sans-serif (Open Sans) | Yes | | `serif` | Serif (Lora) | Yes | | `wrap` | Monospace | Yes | | `mono` | Monospace | No | | `code` | Syntax-highlighted monospace | No | Put it all together, e.g. publish with a sans-serif font: `writeas new --font sans` If you're publishing Markdown, supply the `--md` flag to get a URL back that will render Markdown, e.g.: `writeas new --font sans --md` diff --git a/README.md b/README.md index 65841f4..e648af0 100644 --- a/README.md +++ b/README.md @@ -1,109 +1,113 @@ writeas-cli =========== ![GPL](https://img.shields.io/github/license/writeas/writeas-cli.svg) [![Go Report Card](https://goreportcard.com/badge/github.com/writeas/writeas-cli)](https://goreportcard.com/report/github.com/writeas/writeas-cli) [![#writeas on freenode](https://img.shields.io/badge/freenode-%23writeas-blue.svg)](http://webchat.freenode.net/?channels=writeas) [![Discuss on our forum](https://img.shields.io/discourse/https/discuss.write.as/users.svg?label=forum)](https://discuss.write.as/c/development) Command line interface for [Write.as](https://write.as). Works on Windows, macOS, and Linux. **NOTE: the `master` branch is currently unstable while we prepare the v2.0 release! You should install via official release channel, or build from the `v1.2` tag.** ## Features * Publish anonymously to Write.as * Authenticate with a Write.as account * A stable, easy back-end for your [GUI app](https://write.as/apps/desktop) or desktop-based workflow * Compatible with our [Tor hidden service](http://writeas7pm7rcdqg.onion/) * Locally keeps track of any posts you make * Update and delete posts, anonymous and authenticated * Fetch any post by ID * Add anonymous post credentials (like for one published with the [Android app](https://play.google.com/store/apps/details?id=com.abunchtell.writeas)) for editing ## Installing The easiest way to get the CLI is to download a pre-built executable for your OS. ### Download [![Latest release](https://img.shields.io/github/release/writeas/writeas-cli.svg)](https://github.com/writeas/writeas-cli/releases/latest) ![Total downloads](https://img.shields.io/github/downloads/writeas/writeas-cli/total.svg) Get the latest version for your operating system as a standalone executable. **Windows**
Download the [64-bit](https://github.com/writeas/writeas-cli/releases/download/v1.2/writeas_1.2_windows_amd64.zip) or [32-bit](https://github.com/writeas/writeas-cli/releases/download/v1.2/writeas_1.2_windows_386.zip) executable and put it somewhere in your `%PATH%`. **macOS**
Download the [64-bit](https://github.com/writeas/writeas-cli/releases/download/v1.2/writeas_1.2_darwin_amd64.tar.gz) executable and put it somewhere in your `$PATH`, like `/usr/local/bin`. **Debian-based Linux**
```bash sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys DBE07445 sudo add-apt-repository "deb http://updates.writeas.org xenial main" sudo apt-get update && sudo apt-get install writeas-cli ``` **Linux (other)**
Download the [64-bit](https://github.com/writeas/writeas-cli/releases/download/v1.2/writeas_1.2_linux_amd64.tar.gz) or [32-bit](https://github.com/writeas/writeas-cli/releases/download/v1.2/writeas_1.2_linux_386.tar.gz) executable and put it somewhere in your `$PATH`, like `/usr/local/bin`. ### Go get it ```bash go get github.com/writeas/writeas-cli/cmd/writeas ``` Once this finishes, you'll see `writeas` or `writeas.exe` inside `$GOPATH/bin/`. ## Upgrading To upgrade the CLI, download and replace the executable you downloaded before. If you previously installed with `go get`, run it again with the `-u` option. ```bash go get -u github.com/writeas/writeas-cli/cmd/writeas ``` ## Usage See full usage documentation on our [User Guide](GUIDE.md). ``` writeas [global options] command [command options] [arguments...] COMMANDS: post Alias for default action: create post from stdin new Compose a new post from the command-line and publish publish Publish a file to Write.as delete Delete a post update Update (overwrite) a post get Read a raw post add Add an existing post locally posts List all of your posts blogs List blogs claim Claim local unsynced posts auth Authenticate with Write.as logout Log out of Write.as help, h Shows a list of commands or help for one command GLOBAL OPTIONS: - -c value, -b value Optional blog to post to - --tor, -t Perform action on Tor hidden service - --tor-port value Use a different port to connect to Tor (default: 9150) - --code Specifies this post is code - --md Returns post URL with Markdown enabled - --verbose, -v Make the operation more talkative - --font value Sets post font to given value (default: "mono") - --lang value Sets post language to given ISO 639-1 language code - --user-agent value Sets the User-Agent for API requests - --help, -h show help - --version, -V print the version + -c value, -b value Optional blog to post to + --tor, -t Perform action on Tor hidden service + --tor-port value Use a different port to connect to Tor (default: 9150) + --code Specifies this post is code + --md Returns post URL with Markdown enabled + --verbose, -v Make the operation more talkative + --font value Sets post font to given value (default: "mono") + --lang value Sets post language to given ISO 639-1 language code + --user-agent value Sets the User-Agent for API requests + --host value, -H value Operate against a custom hostname + --user value, -u value Use authenticated user, other than default + --help, -h show help + --version, -V print the version ``` +> Note: the host and user flags are only available in `wf` the community edition + ## Contributing to the CLI For a complete guide to contributing, see the [Contribution Guide](.github/CONTRIBUTING.md). We welcome any kind of contributions including documentation, organizational improvements, tutorials, bug reports, feature requests, new features, answering questions, etc. ### Getting Support We're available on [several channels](https://write.as/contact), and prefer our [forum](https://discuss.write.as) for project discussion. Please don't use the GitHub issue tracker to ask questions. ### Reporting Issues If you believe you have found a bug in the CLI or its documentation, file an issue on this repo. If you're not sure if it's a bug or not, [reach out to us](https://write.as/contact) in one way or another. Be sure to provide the version of the CLI (with `writeas --version`) in your report.