Skip to content

Latest commit

 

History

History
164 lines (114 loc) · 5.48 KB

GUIDE.md

File metadata and controls

164 lines (114 loc) · 5.48 KB

WriteFreely CLI User Guide

The WriteFreely Command-Line Interface (CLI) is a cross-platform tool for publishing text to any WriteFreely instance. It is designed to be simple, scriptable, do one job (publishing) well, and work as you'd expect with other command-line tools.

WriteFreely is the software behind Write.as. While the WriteFreely CLI supports publishing to Write.as, we recommend using the dedicated Write.as CLI to get the full features of the platform, including anonymous publishing.

The WriteFreely CLI is compatible with WriteFreely v0.11 or later.

Uses

These are a few common uses for wf. If you get stuck or want to know more, run wf [command] --help. If you still have questions, ask us.

Overview

   wf [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
     delete   Delete a post
     update   Update (overwrite) a post
     get      Read a raw post
     posts    List all of your posts
     blogs    List blogs
     auth     Authenticate with a WriteFreely instance
     logout   Log out of a WriteFreely instance
     help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   -c value, -b value      Optional blog to post to
   --insecure              Send request insecurely.
   --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
   --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  Use the given WriteFreely instance hostname
   --user value, -u value  Use the given account username
   --help, -h              show help
   --version, -V           print the version

Authenticate

To use the WriteFreely CLI, you'll first need to authenticate with the WriteFreely instance you want to interact with.

You may authenticate with as many WriteFreely instances and accounts as you want. But the first account you authenticate with will automatically be set as the default instance to operate on, so you don't have to supply --host and --user with every command.

$ wf --host pencil.writefree.ly auth username
Password: ************

In this example, you'll be authenticated as the user username on the WriteFreely instance https://pencil.writefree.ly.

Choosing an account

To select the WriteFreely instance and account you want to interact with, supply the --host and --user flags at the beginning of your wf command, e.g.:

$ wf --host pencil.writefree.ly --user username <subcommand>

If you're authenticated with only one account on any given WriteFreely instance, you only need to supply the --host, and wf will automatically use the correct account. E.g.:

$ wf --host pencil.writefree.ly <subcommand>

If a default account is set in ~/.writefreely/config.ini and you want to use it, you don't need to supply any additional arguments. E.g.:

$ wf <subcommand>

Share something

By default, wf 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.

$ echo "Hello world!" | wf
https://pencil.writefree.ly/aaaaazzzzz

This is generally more useful for posting terminal output or code, like so (the --code flag turns on syntax highlighting):

macOS / Linux: cat cmd/wf/cli.go | wf --code

Windows: type cmd/wf/cli.go | wf.exe --code

Output a post

This outputs any WriteFreely post with the given ID.

$ wf get aaaaazzzzz
Hello world!

List all blogs

This will output a list of the authenticated user's blogs.

$ wf blogs
Alias    Title
user     An Example Blog
dev      My Dev Log

List posts

This lists all draft posts you've published.

Pass the --url flag to show the list with full post URLs.

$ wf posts
aaaaazzzzz

$ wf posts -url
https://pencil.writefree.ly/aaaaazzzzz

$ wf posts
ID
aaaaazzzzz

Delete a post

This permanently deletes a post with the given ID.

$ wf delete aaaaazzzzz

Update a post

This completely overwrites an existing post with the given ID.

$ echo "See you later!" | wf update aaaaazzzzz

Composing posts

If you simply have a penchant for never leaving your keyboard, wf is great for composing new posts from the command-line. Just use the new subcommand.

wf 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: wf new --font sans