Realtime logs (or any stdout basically!) sharing by just piping squirrel.
- I'm lazy
- I wanted to learn Go
- I wanted to implement a websocket server using Go
- I wanted to be used on crossplatform without installing any extra dependencies (that's why not Nodejs or ink)
- I'm tired of requesting people to send me snippets of logs, so that i can analyze, or grep the lines
- I love CLI apps
- Probably people will find this useful?
- I wanted to use squirrel as a name of something xD
- Because why not?
Currently can head over to releases, and choose the suitable package for you. Currently this was tested on Ubuntu and OSX Monterey only though
If you're on Linux, then you can choose the package based on your distribution and install it, for example on Ubuntu/Debian:
curl -fLO https://github.com/omarahm3/squirrel/releases/download/v<VERSION>/squirrel_<VERSION>_linux_amd64.deb
sudo apt install -y ./squirrel_<VERSION>_linux_amd64.deb
If you're on a different OS, then you can use download the compressed files, and move these files to your bin folder accordingly, for example on Ubuntu/Debian:
curl -fLO https://github.com/omarahm3/squirrel/releases/download/v<VERSION>/squirrel_<VERSION>_Linux_x86_64.tar.gz
tar xf squirrel_<VERSION>_Linux_x86_64.tar.gz
mv ./squirrel ~/.local/bin/
Or if you have go installed, you can always install squirrel client as a Go package by doing so:
go install github.com/omarahm3/squirrel/cmd/squirrel@latest
Note: Installing squirrel as a go package will install it as a development ready package, which is going to need to be configured either by Environment variables or passing options to the CLI, Refer to configuration section for more details
Squirrel is available as a docker image that you can use directly as well, run squirrel:
# Help command
docker run -i omarahm3/squirrel:latest squirrel -h
# You can also pipe it like this
cat myfile.txt | docker run -i omarahm3/squirrel:latest squirrel -o -u
Squirreld (daemon/server) is also available via docker, and high customizable using either flags, or environment variables, check configuration to know how to customize it accordingly
# Help command
docker run -i omarahm3/squirreld:latest squirreld -h
# Configure it using flags
docker run -i omarahm3/squirreld:latest squirreld -domain=localhost -env=dev -log=debug -port=3000
# or using environment variables
docker run -e DOMAIN=localhost -e APP_ENV=dev -e LOG_LEVEL=debug -e PORT=3000 -i omarahm3/squirreld:latest squirreld
Squirrel has no commands, the only way it can be used is via piping it to stdout of another command, for example
$ for i in $(seq 1 50); do echo "Example Message #$i"; sleep 1; done | squirrel -o -u
➜ ID: [ 315c77cd-7ac1-4487-adf8-d205471f0771 ]
➜ Link: [ https://squirrel-jwls9.ondigitalocean.app/client/315c77cd-7ac1-4487-adf8-d205471f0771 ]
➜ Url is copied to your clipboard
📢 Squirrel is waiting for listeners to begin piping stdout...
This will print a shareable link and ID that you can use to send to the person you want to share the output of this for loop with, however squirrel will not start reading stdout till the other end is connected and ready to receive the actual output.
The other end (or maybe yourself) can then open the link and you'll begin to see that messages are coming in, which are the output of the for loop we just piped. Or if person prefer to use terminal, then another squirrel can be used in listening mode, but then peer
option is must be supplied with the ID of the broadcaster:
squirrel -l --peer=315c77cd-7ac1-4487-adf8-d205471f0771
Squirrel can be configured by passing options/flags to the CLI, or for some options you can use ENV variables as well. Just note that ENV variables have more priority over flags. Squirrel can be run in 2 different modes too:
- Broadcasting: which is the default behavior and the initial mode of squirrel where broadcaster is piping squirrel to stdout
- Listening: in which the other end subscriber which is the one who is listening for broadcaster messages
ENV Variables:
APP_ENV
- Set the app environment mode (prod
ordev
default isprod
)DOMAIN
- Set the server domain in which CLI is going to send events toLOG_LEVEL
- Set the current log level of the CLI (default iserror
)- Log levels are:
- error
- warn
- info
- debug
- Log levels are:
Flags:
--env
- Set app environment mode (same asAPP_ENV
)--domain
- Set the server domain in which CLI is going to send events to (same asDOMAIN
)--log
- Set the current log level of the CLI (same asDOMAIN
)--peer
- Peer (broadcaster) ID that squirrel is going to listen to (must be supplied in listen mode-l/--listen
)-l
or--listen
- Set the current mode of the CLI to listen instead of broadcasting-o
or--show-output
- Show the output of what is being piped to squirrel on the current session as well-u
or--copy-url
- Copy shareable link to the clipboard
You can always run:
squirrel -h
and see all of the available options
This package is built into 2 different applications, the main one and probably most of the users will be interested in is squirrel which is the client/CLI, and the other one is squirreld which is the server daemon that will be responsible of managing and routing broadcasters messages to their corresponding subscribers.
Squirreld is a websocket server, that each of the broadcasters and subscribers is connecting to, so that they can exchange events between each other, that's is how we're making sure that stdout messages are exchanged in realtime from broadcasters to subscribers. Currently server is hosted by me on one of Digitalocean servers, but this is subject to change indeed.
All of server configuration can be tweaked using ENV variables or passing flags to squirreld, here is the detailed options and ENV variables list:
--env
orAPP_ENV
- Set server environment mode (prod
ordev
default isprod
)--domain
orDOMAIN
- Set the current server domain--log
orLOG_LEVEL
- Set the current log level of the server (same as squirrel log levels)--port
orPORT
- Set the current port that server is going to listen to (default is3000
)--read-buffer-size
orREAD_BUFFER_SIZE
- Websocket server read buffer size (default is0
)--write-buffer-size
orWRITE_BUFFER_SIZE
- Websocket server write buffer size (default is0
)--max-message-size
orMAX_MESSAGE_SIZE
- Websocket server maximum message size (default is1024
)
Same as squirrel, ENV variables have more priority than flags as well.
This is pretty immature Go project, i'm still learning Go by actually doing and maintaining this project, it gave me the opportunity to explore various topics that i want to get familiar with using Go such as backend (http, and websocket), templates, CLI, Go routines and channels ..etc Contributions are more than welcome, i indeed would like to see how this project will scale.