diff --git a/GUIDE.md b/GUIDE.md index 5588261..07b308f 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -1,103 +1,107 @@ # 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". **Note** accounts are not supported in CLI v1.0. They'll be available in [v2.0](https://github.com/writeas/writeas-cli/milestone/4). ## 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 delete Delete a post update Update (overwrite) a post get Read a raw post add Add an existing post locally list List local posts help, h Shows a list of commands or help for one command GLOBAL OPTIONS: --tor, -t Perform action on Tor hidden service --tor-port "9150" Use a different port to connect to Tor --code Specifies this post is code --verbose, -v Make the operation more talkative --font value Sets post font to given value (default: "mono") --help, -h show help --version, -v print the version ``` #### 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/aaaaaaaaaaaa ``` 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 aaaaaaaaaaaa Hello world! ``` #### List all published posts -This lists all posts you've published from your device. Pass the `--url` flag to show the list with full URLs. +This lists all posts you've published from your device. + +Pass the `--url` flag to show the list with full post URLs, and the `--md` flag to return URLs with Markdown enabled. ```bash $ writeas list aaaaaaaaaaaa ``` #### Delete a post This permanently deletes a post you own. ```bash $ writeas delete aaaaaaaaaaaa ``` #### Update a post This completely overwrites an existing post you own. ```bash $ echo "See you later!" | writeas update aaaaaaaaaaaa ``` ### 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/cmd/writeas/api.go b/cmd/writeas/api.go index ab830ca..1f441da 100644 --- a/cmd/writeas/api.go +++ b/cmd/writeas/api.go @@ -1,201 +1,205 @@ package main import ( "bytes" "fmt" "github.com/atotto/clipboard" "gopkg.in/urfave/cli.v1" "io/ioutil" "net/http" "net/url" "strconv" "strings" ) const ( defaultUserAgent = "writeas-cli v" + version ) func userAgent(c *cli.Context) string { ua := c.String("user-agent") if ua == "" { return defaultUserAgent } return ua + " (" + defaultUserAgent + ")" } func client(read, tor bool, path, query string) (string, *http.Client) { var u *url.URL var client *http.Client if tor { u, _ = url.ParseRequestURI(hiddenAPIURL) u.Path = "/api/" + path client = torClient() } else { u, _ = url.ParseRequestURI(apiURL) u.Path = "/api/" + path client = &http.Client{} } if query != "" { u.RawQuery = query } urlStr := fmt.Sprintf("%v", u) return urlStr, client } // DoFetch retrieves the Write.as post with the given friendlyID, // optionally via the Tor hidden service. func DoFetch(friendlyID, ua string, tor bool) error { path := friendlyID urlStr, client := client(true, tor, path, "") r, _ := http.NewRequest("GET", urlStr, nil) r.Header.Add("User-Agent", ua) resp, err := client.Do(r) if err != nil { return err } defer resp.Body.Close() if resp.StatusCode == http.StatusOK { content, err := ioutil.ReadAll(resp.Body) if err != nil { return err } fmt.Printf("%s\n", string(content)) } else if resp.StatusCode == http.StatusNotFound { return ErrPostNotFound } else if resp.StatusCode == http.StatusGone { } else { return fmt.Errorf("Unable to get post: %s", resp.Status) } return nil } // DoPost creates a Write.as post, returning an error if it was // unsuccessful. func DoPost(c *cli.Context, post []byte, font string, encrypt, tor, code bool) error { data := url.Values{} data.Set("w", string(post)) if encrypt { data.Add("e", "") } data.Add("font", getFont(code, font)) urlStr, client := client(false, tor, "", "") r, _ := http.NewRequest("POST", urlStr, bytes.NewBufferString(data.Encode())) r.Header.Add("User-Agent", userAgent(c)) r.Header.Add("Content-Type", "application/x-www-form-urlencoded") r.Header.Add("Content-Length", strconv.Itoa(len(data.Encode()))) resp, err := client.Do(r) if err != nil { return err } defer resp.Body.Close() if resp.StatusCode == http.StatusOK { content, err := ioutil.ReadAll(resp.Body) if err != nil { return err } nlPos := strings.Index(string(content), "\n") url := content[:nlPos] idPos := strings.LastIndex(string(url), "/") + 1 id := string(url[idPos:]) token := string(content[nlPos+1 : len(content)-1]) addPost(id, token) + // Output URL in requested format + if c.Bool("md") { + url = append(url, []byte(".md")...) + } // Copy URL to clipboard err = clipboard.WriteAll(string(url)) if err != nil { Errorln("writeas: Didn't copy to clipboard: %s", err) } else { Info(c, "Copied to clipboard.") } // Output URL fmt.Printf("%s\n", url) } else { return fmt.Errorf("Unable to post: %s", resp.Status) } return nil } // DoUpdate updates the given post on Write.as. func DoUpdate(c *cli.Context, post []byte, friendlyID, token, font string, tor, code bool) error { urlStr, client := client(false, tor, friendlyID, fmt.Sprintf("t=%s", token)) data := url.Values{} data.Set("w", string(post)) if code || font != "" { // Only update font if explicitly changed data.Add("font", getFont(code, font)) } r, _ := http.NewRequest("POST", urlStr, bytes.NewBufferString(data.Encode())) r.Header.Add("User-Agent", userAgent(c)) r.Header.Add("Content-Type", "application/x-www-form-urlencoded") r.Header.Add("Content-Length", strconv.Itoa(len(data.Encode()))) resp, err := client.Do(r) if err != nil { return err } defer resp.Body.Close() if resp.StatusCode == http.StatusOK { if tor { Info(c, "Post updated via hidden service.") } else { Info(c, "Post updated.") } } else { if debug { ErrorlnQuit("Problem updating: %s", resp.Status) } else { return fmt.Errorf("Post doesn't exist, or bad edit token given.") } } return nil } // DoDelete deletes the given post on Write.as. func DoDelete(c *cli.Context, friendlyID, token string, tor bool) error { urlStr, client := client(false, tor, friendlyID, fmt.Sprintf("t=%s", token)) r, _ := http.NewRequest("DELETE", urlStr, nil) r.Header.Add("User-Agent", userAgent(c)) r.Header.Add("Content-Type", "application/x-www-form-urlencoded") resp, err := client.Do(r) if err != nil { return err } defer resp.Body.Close() if resp.StatusCode == http.StatusOK { if tor { Info(c, "Post deleted from hidden service.") } else { Info(c, "Post deleted.") } removePost(friendlyID) } else { if debug { ErrorlnQuit("Problem deleting: %s", resp.Status) } else { return fmt.Errorf("Post doesn't exist, or bad edit token given.") } } return nil } diff --git a/cmd/writeas/cli.go b/cmd/writeas/cli.go index 2a41acd..b96e77d 100644 --- a/cmd/writeas/cli.go +++ b/cmd/writeas/cli.go @@ -1,262 +1,270 @@ package main import ( "bufio" "gopkg.in/urfave/cli.v1" "io" "log" "os" ) // API constants for communicating with Write.as. const ( apiURL = "https://write.as" hiddenAPIURL = "http://writeas7pm7rcdqg.onion" readAPIURL = "https://write.as" ) // Application constants. const ( version = "1.1" ) // Defaults for posts on Write.as. const ( defaultFont = PostFontMono ) // Available flags for creating posts var postFlags = []cli.Flag{ cli.BoolFlag{ Name: "tor, t", Usage: "Perform action on Tor hidden service", }, cli.IntFlag{ Name: "tor-port", Usage: "Use a different port to connect to Tor", Value: 9150, }, cli.BoolFlag{ Name: "code", Usage: "Specifies this post is code", }, + cli.BoolFlag{ + Name: "md", + Usage: "Returns post URL with Markdown enabled", + }, cli.BoolFlag{ Name: "verbose, v", Usage: "Make the operation more talkative", }, cli.StringFlag{ Name: "font", Usage: "Sets post font to given value", Value: defaultFont, }, cli.StringFlag{ Name: "user-agent", Usage: "Sets the User-Agent for API requests", Value: "", }, } func main() { initialize() cli.VersionFlag = cli.BoolFlag{ Name: "version, V", Usage: "print the version", } // Run the app app := cli.NewApp() app.Name = "writeas" app.Version = version app.Usage = "Publish text quickly" app.Authors = []cli.Author{ { Name: "Write.as", Email: "hello@write.as", }, } app.Action = cmdPost app.Flags = postFlags app.Commands = []cli.Command{ { Name: "post", Usage: "Alias for default action: create post from stdin", Action: cmdPost, Flags: postFlags, Description: `Create a new post on Write.as from stdin. Use the --code flag to indicate that the post should use syntax highlighting. Or use the --font [value] argument to set the post's appearance, where [value] is mono, monospace (default), wrap (monospace font with word wrapping), serif, or sans.`, }, { Name: "new", Usage: "Compose a new post from the command-line and publish", Description: `An alternative to piping data to the program. On Windows, this will use 'copy con' to start reading what you input from the prompt. Press F6 or Ctrl-Z then Enter to end input. On *nix, this will use the best available text editor, starting with the value set to the WRITAS_EDITOR or EDITOR environment variable, or vim, or finally nano. Use the --code flag to indicate that the post should use syntax highlighting. Or use the --font [value] argument to set the post's appearance, where [value] is mono, monospace (default), wrap (monospace font with word wrapping), serif, or sans. If posting fails for any reason, 'writeas' will show you the temporary file location and how to pipe it to 'writeas' to retry.`, Action: cmdNew, Flags: postFlags, }, { Name: "delete", Usage: "Delete a post", Action: cmdDelete, Flags: []cli.Flag{ cli.BoolFlag{ Name: "tor, t", Usage: "Delete via Tor hidden service", }, cli.IntFlag{ Name: "tor-port", Usage: "Use a different port to connect to Tor", Value: 9150, }, }, }, { Name: "update", Usage: "Update (overwrite) a post", Action: cmdUpdate, Flags: []cli.Flag{ cli.BoolFlag{ Name: "tor, t", Usage: "Update via Tor hidden service", }, cli.IntFlag{ Name: "tor-port", Usage: "Use a different port to connect to Tor", Value: 9150, }, cli.BoolFlag{ Name: "code", Usage: "Specifies this post is code", }, cli.StringFlag{ Name: "font", Usage: "Sets post font to given value", }, }, }, { Name: "get", Usage: "Read a raw post", Action: cmdGet, Flags: []cli.Flag{ cli.BoolFlag{ Name: "tor, t", Usage: "Get from Tor hidden service", }, cli.IntFlag{ Name: "tor-port", Usage: "Use a different port to connect to Tor", Value: 9150, }, }, }, { Name: "add", Usage: "Add an existing post locally", Description: `A way to add an existing post to your local store for easy editing later. This requires a post ID (from https://write.as/[ID]) and an Edit Token (exported from another Write.as client, such as the Android app). `, Action: cmdAdd, }, { Name: "list", Usage: "List local posts", Action: cmdList, Flags: []cli.Flag{ cli.BoolFlag{ Name: "id", Usage: "Show list with post IDs (default)", }, + cli.BoolFlag{ + Name: "md", + Usage: "Use with --url to return URLs with Markdown enabled", + }, cli.BoolFlag{ Name: "url", Usage: "Show list with URLs", }, }, }, } cli.CommandHelpTemplate = `NAME: {{.Name}} - {{.Usage}} USAGE: writeas {{.Name}}{{if .Flags}} [command options]{{end}} [arguments...]{{if .Description}} DESCRIPTION: {{.Description}}{{end}}{{if .Flags}} OPTIONS: {{range .Flags}}{{.}} {{end}}{{ end }} ` app.Run(os.Args) } func initialize() { // Ensure we have a data directory to use if !dataDirExists() { createDataDir() } } func readStdIn() []byte { numBytes, numChunks := int64(0), int64(0) r := bufio.NewReader(os.Stdin) fullPost := []byte{} buf := make([]byte, 0, 1024) for { n, err := r.Read(buf[:cap(buf)]) buf = buf[:n] if n == 0 { if err == nil { continue } if err == io.EOF { break } log.Fatal(err) } numChunks++ numBytes += int64(len(buf)) fullPost = append(fullPost, buf...) if err != nil && err != io.EOF { log.Fatal(err) } } return fullPost } func handlePost(fullPost []byte, c *cli.Context) error { tor := c.Bool("tor") || c.Bool("t") if c.Int("tor-port") != 0 { torPort = c.Int("tor-port") } if tor { Info(c, "Posting to hidden service...") } else { Info(c, "Posting...") } return DoPost(c, fullPost, c.String("font"), false, tor, c.Bool("code")) } diff --git a/cmd/writeas/commands.go b/cmd/writeas/commands.go index b9d5399..f984848 100644 --- a/cmd/writeas/commands.go +++ b/cmd/writeas/commands.go @@ -1,154 +1,159 @@ package main import ( "fmt" "gopkg.in/urfave/cli.v1" "os" ) func cmdPost(c *cli.Context) error { err := handlePost(readStdIn(), c) return err } func cmdNew(c *cli.Context) error { fname, p := composeNewPost() if p == nil { // Assume composeNewPost already told us what the error was. Abort now. os.Exit(1) } // Ensure we have something to post if len(*p) == 0 { // Clean up temporary post if fname != "" { os.Remove(fname) } InfolnQuit("Empty post. Bye!") } err := handlePost(*p, c) if err != nil { Errorln("Error posting: %s", err) Errorln(messageRetryCompose(fname)) return cli.NewExitError("", 1) } // Clean up temporary post if fname != "" { os.Remove(fname) } return nil } func cmdDelete(c *cli.Context) error { friendlyID := c.Args().Get(0) token := c.Args().Get(1) if friendlyID == "" { return cli.NewExitError("usage: writeas delete []", 1) } if token == "" { // Search for the token locally token = tokenFromID(friendlyID) if token == "" { Errorln("Couldn't find an edit token locally. Did you create this post here?") ErrorlnQuit("If you have an edit token, use: writeas delete %s ", friendlyID) } } tor := c.Bool("tor") || c.Bool("t") if c.Int("tor-port") != 0 { torPort = c.Int("tor-port") } if tor { Info(c, "Deleting via hidden service...") } else { Info(c, "Deleting...") } return DoDelete(c, friendlyID, token, tor) } func cmdUpdate(c *cli.Context) error { friendlyID := c.Args().Get(0) token := c.Args().Get(1) if friendlyID == "" { return cli.NewExitError("usage: writeas update []", 1) } if token == "" { // Search for the token locally token = tokenFromID(friendlyID) if token == "" { Errorln("Couldn't find an edit token locally. Did you create this post here?") ErrorlnQuit("If you have an edit token, use: writeas update %s ", friendlyID) } } // Read post body fullPost := readStdIn() tor := c.Bool("tor") || c.Bool("t") if c.Int("tor-port") != 0 { torPort = c.Int("tor-port") } if tor { Info(c, "Updating via hidden service...") } else { Info(c, "Updating...") } return DoUpdate(c, fullPost, friendlyID, token, c.String("font"), tor, c.Bool("code")) } func cmdGet(c *cli.Context) error { friendlyID := c.Args().Get(0) if friendlyID == "" { return cli.NewExitError("usage: writeas get ", 1) } tor := c.Bool("tor") || c.Bool("t") if c.Int("tor-port") != 0 { torPort = c.Int("tor-port") } if tor { Info(c, "Getting via hidden service...") } else { Info(c, "Getting...") } return DoFetch(friendlyID, userAgent(c), tor) } func cmdAdd(c *cli.Context) error { friendlyID := c.Args().Get(0) token := c.Args().Get(1) if friendlyID == "" || token == "" { return cli.NewExitError("usage: writeas add ", 1) } err := addPost(friendlyID, token) return err } func cmdList(c *cli.Context) error { urls := c.Bool("url") ids := c.Bool("id") var p Post posts := getPosts() for i := range *posts { p = (*posts)[len(*posts)-1-i] if ids || !urls { fmt.Printf("%s ", p.ID) } if urls { - fmt.Printf("https://write.as/%s ", p.ID) + ext := "" + // Output URL in requested format + if c.Bool("md") { + ext = ".md" + } + fmt.Printf("https://write.as/%s%s ", p.ID, ext) } fmt.Print("\n") } return nil }