https://github.com/candidtim/hnwelcome
CLI application to show top Hacker News stories
https://github.com/candidtim/hnwelcome
Last synced: about 1 month ago
JSON representation
CLI application to show top Hacker News stories
- Host: GitHub
- URL: https://github.com/candidtim/hnwelcome
- Owner: candidtim
- License: mit
- Created: 2023-05-31T19:01:59.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-06-01T00:14:19.000Z (about 3 years ago)
- Last Synced: 2025-02-25T03:42:34.954Z (over 1 year ago)
- Language: Go
- Size: 13.7 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# HN Welcome
___________________________________________________________________
/ Show HN: `hnwelcome` is a CLI app to show top Hacker News stories \
| https://github.com/candidtim/hnwelcome |
\ https://news.ycombinator.com/item?id=36146152 /
-------------------------------------------------------------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
A simple and fast CLI appliaction to show top
[Hacker News](https://news.ycombinator.com/) stories in the command line. Works
best with [`cowsay`](https://en.wikipedia.org/wiki/Cowsay). Use it like
[`fortune`](https://en.wikipedia.org/wiki/Fortune_(Unix))
and tap into an endless supply of top Hacker News stories.
## Installation
With Go tool chain:
$ go install github.com/candidtim/hnwelcome@1.0.1
Or, download a binary for your OS from the
[Releases](https://github.com/candidtim/hnwelcome/releases) page.
If nothing else works, clone the repository and build with `go build .`.
## Usage
To see one of the top 5 stories:
$ hnwelcome
Hacking my “smart” toothbrush [467]
https://kuenzi.dev/toothbrush/
https://news.ycombinator.com/item?id=36128617
One of the newest stories:
$ hnwelcome --newest
To choose randomly between the top 10 stories (instead of the default of top 5):
$ hnwelcome -n 10
Pipe to `cowsay`:
$ hnwelcome | cowsay -n
_______________________________________________
/ Hacking my “smart” toothbrush [467] \
| https://kuenzi.dev/toothbrush/ |
\ https://news.ycombinator.com/item?id=36128617 /
-----------------------------------------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
See the built-in help for more options, or read below for customization.
### Show the top stories in new shell sessions
If you want to see one of the top stories every time you start a terminal, you
may run `hnwelcome | cowsay -n` in your shell's `.*rc` file
(`.bashrc`, `.zshrc`).
### Show the top stories in Vim on startup
For Vim users, if you want to see top HN stories in a welcome screen, my
recommendation is to use [vim-startify](https://github.com/mhinz/vim-startify)
with the following configuration:
let g:startify_custom_header = split(system('hnwelcome | cowsay -n'), '\n')
### Customize the output format
To customize the output format pass a `--template` to use for the formatting.
The template should use the Golang
[template syntax](https://pkg.go.dev/text/template). Available variables are:
`By`, `Time`, `Title`, `Score`, `Url`, `Id`. See the
[Hacker News API documentation](https://github.com/HackerNews/API#items) for
more details about their values.
$ hnwelcome --template PATH
For example, to print out only the title and the author:
$ hnwelcome --template "{{.Title}} by {{.By}}"
The default template is:
{{.Title}} [{{.Score}}]
{{.Url}}
https://news.ycombinator.com/item?id={{.Id}}
### Latency and timeout
Due to the Internet connection and the API latency, `hnwelcome` may slow down
the shell or Vim startup time if you configure them to run it on startup. By
default, `hnwelcome` will try to fetch the story in under 2 seconds, or timeout
nicely otherwise. You can change the timeout value with a `--timeout` argument.
For example, if you have a somewhat slow Internet connection and you are ready
to wait for up to 5 seconds:
hnwelcome --timetout 5s
## License
[The MIT License](http://opensource.org/licenses/MIT)