browsh/README.md

[![Follow @brow_sh](https://img.shields.io/twitter/follow/brow_sh.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=brow_sh)

![Browsh Logo](https://www.brow.sh/assets/images/browsh-header.jpg)

**A fully interactive, real-time, and modern text-based browser rendered to TTYs and browsers**

![Browsh GIF](https://media.giphy.com/media/bbsmVkYjPdOKHhMXOO/giphy.gif)

## Why use Browsh?

Not all the world has good Internet.

If you only have a 3kbps internet connection tethered from a phone,
then it's good to SSH into a server and browse the web through, say,
[elinks](https://github.com/browsh-org/browsh/issues/17). That way the
_server_ downloads the web pages and uses the limited bandwidth of an
SSH connection to display the result. However, traditional text-based browsers
lack JS and all other modern HTML5 support. Browsh is different
in that it's backed by a real browser, namely headless Firefox,
to create a purely text-based version of web pages and web apps. These can be easily
rendered in a terminal or indeed, ironically, in another browser. Do note that currently the browser client doesn't have feature parity with the terminal client.

Why not VNC? Well VNC is certainly one solution but it doesn't quite
have the same ability to deal with extremely bad Internet. Terminal 
Browsh can also use MoSH to further reduce bandwidth and increase stability
of the connection. Mosh offers features like automatic
reconnection of dropped or roamed connections and diff-only screen updates.
Furthermore, other than SSH or MoSH, terminal Browsh doesn't require a client
like VNC.

One final reason to use terminal Browsh could be to offload the battery-drain of a modern
browser from your laptop or low-powered device like a Raspberry Pi. If you're a CLI-native,
then you could potentially get a few more hours of life if your CPU-hungry browser
is running somewhere else on mains electricity.

## Installation

Download a binary from the [releases](https://github.com/browsh-org/browsh/releases) (~11MB).
You will need to have [Firefox](https://www.mozilla.org/en-US/firefox/new/) already installed.

Or download and run the Docker image (~230MB) with:
    `docker run --rm -it browsh/browsh`

## Usage
Most keys and mouse gestures should work as you'd expect on a desktop
browser.

For full documentation click [here](https://www.brow.sh/docs/introduction/).

## Contributing
_Note that some of these instructions may be out of date (July 2022)_

For generic Linux systems you can follow [this guide](https://github.com/browsh-org/browsh/blob/master/SETUP_DEV_LINUX.md) on how to setup a build environment, that you may be able to adapt for other systems as well.

Windows users can follow [this guide](https://github.com/browsh-org/browsh/blob/master/SETUP_DEV_WIN.md) in order to set up a build environment.

Mac users may follow [this guide](https://github.com/browsh-org/browsh/blob/master/SETUP_DEV_OSX.md) that goes through the steps of setting up a build environment.

### Communication
Questions about Brow.sh? Stuck trying to resolve a tricky issue? Try:
  - [Github Discussions](https://github.com/browsh-org/browsh/discussions)
  - [Gitter](https://gitter.im/browsh)
    
## Tests

For the webextension: in `webext/` folder, `npm test`    
For CLI unit tests: in `/interfacer` run `go test src/browsh/*.go`    
For CLI E2E tests: in `/interfacer` run `go test test/tty/*.go`    
For HTTP Service tests: in `/interfacer` run `go test test/http-server/*.go`    

## Special Thanks
  * [@tobimensch](https://github.com/tobimensch) For essential early feedback and user testing.
  * [@arasatasaygin](https://github.com/arasatasaygin) For the Browsh logo.

## Donating
Please consider donating: https://www.brow.sh/donate

## License
GNU Lesser General Public License v2.1
chore: Update README 2022-07-17 01:36:30 +00:00			`[![Follow @brow_sh](https://img.shields.io/twitter/follow/brow_sh.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=brow_sh)`
Don't use `--new-instance`, `-P` when launching FF 2018-01-24 02:59:57 +00:00
Add logo to TTY startup. README updates 2018-07-06 05:06:49 +00:00			`![Browsh Logo](https://www.brow.sh/assets/images/browsh-header.jpg)`
Updated Dockerfile with some Go build lines. Added README 2016-05-21 05:20:16 +00:00
update main documentation to improve spelling (#330) Thank you! 2020-07-08 12:17:29 +00:00			`A fully interactive, real-time, and modern text-based browser rendered to TTYs and browsers`
Don't use `--new-instance`, `-P` when launching FF 2018-01-24 02:59:57 +00:00
update main documentation to improve spelling (#330) Thank you! 2020-07-08 12:17:29 +00:00			`![Browsh GIF](https://media.giphy.com/media/bbsmVkYjPdOKHhMXOO/giphy.gif)`
Add gif to README 2018-07-07 15:12:43 +00:00
Update README.md Changed "Why?" to "Why use Browsh?" Removed avoidable phrases such as "that" and "and uses that" Divided a run-on sentence by using a period Switched "Firefox =>57" to "Firefox 57 (or higher) Shortened the documentation sentence and link 2018-07-15 09:04:26 +00:00			`## Why use Browsh?`
Don't use `--new-instance`, `-P` when launching FF 2018-01-24 02:59:57 +00:00
README updates Make it less about me. 2018-02-09 03:33:59 +00:00			`Not all the world has good Internet.`

Cohesion, fix structural error, improve word choice "If all you have is a 3kbps connection tethered" --> "If you only have a 3kbps internet connection" "But traditional text-based browsers..." --> "However, traditional text-based browsers" "lack JS support and all other modern HTML5 goodness." --> "lack JS and all other modern HTML5 support." "few more hours life" --> "few more hours of life" 2018-07-18 02:51:35 +00:00			`If you only have a 3kbps internet connection tethered from a phone,`
Add logo to TTY startup. README updates 2018-07-06 05:06:49 +00:00			`then it's good to SSH into a server and browse the web through, say,`
Change 'texttop' refs to 'browsh' 2018-07-08 09:07:10 +00:00			`[elinks](https://github.com/browsh-org/browsh/issues/17). That way the`
README updates Make it less about me. 2018-02-09 03:33:59 +00:00			`_server_ downloads the web pages and uses the limited bandwidth of an`
Cohesion, fix structural error, improve word choice "If all you have is a 3kbps connection tethered" --> "If you only have a 3kbps internet connection" "But traditional text-based browsers..." --> "However, traditional text-based browsers" "lack JS support and all other modern HTML5 goodness." --> "lack JS and all other modern HTML5 support." "few more hours life" --> "few more hours of life" 2018-07-18 02:51:35 +00:00			`SSH connection to display the result. However, traditional text-based browsers`
			`lack JS and all other modern HTML5 support. Browsh is different`
Update README.md Changed "Why?" to "Why use Browsh?" Removed avoidable phrases such as "that" and "and uses that" Divided a run-on sentence by using a period Switched "Firefox =>57" to "Firefox 57 (or higher) Shortened the documentation sentence and link 2018-07-15 09:04:26 +00:00			`in that it's backed by a real browser, namely headless Firefox,`
			`to create a purely text-based version of web pages and web apps. These can be easily`
Reverted one change Switched "a feature parity" to "feature parity" 2018-07-15 10:42:17 +00:00			`rendered in a terminal or indeed, ironically, in another browser. Do note that currently the browser client doesn't have feature parity with the terminal client.`
First draft of integration tests 2018-01-23 04:28:56 +00:00
			`Why not VNC? Well VNC is certainly one solution but it doesn't quite`
Update README.md Changed "Why?" to "Why use Browsh?" Removed avoidable phrases such as "that" and "and uses that" Divided a run-on sentence by using a period Switched "Firefox =>57" to "Firefox 57 (or higher) Shortened the documentation sentence and link 2018-07-15 09:04:26 +00:00			`have the same ability to deal with extremely bad Internet. Terminal`
			`Browsh can also use MoSH to further reduce bandwidth and increase stability`
Add logo to TTY startup. README updates 2018-07-06 05:06:49 +00:00			`of the connection. Mosh offers features like automatic`
			`reconnection of dropped or roamed connections and diff-only screen updates.`
			`Furthermore, other than SSH or MoSH, terminal Browsh doesn't require a client`
Don't use `--new-instance`, `-P` when launching FF 2018-01-24 02:59:57 +00:00			`like VNC.`

Add logo to TTY startup. README updates 2018-07-06 05:06:49 +00:00			`One final reason to use terminal Browsh could be to offload the battery-drain of a modern`
			`browser from your laptop or low-powered device like a Raspberry Pi. If you're a CLI-native,`
Cohesion, fix structural error, improve word choice "If all you have is a 3kbps connection tethered" --> "If you only have a 3kbps internet connection" "But traditional text-based browsers..." --> "However, traditional text-based browsers" "lack JS support and all other modern HTML5 goodness." --> "lack JS and all other modern HTML5 support." "few more hours life" --> "few more hours of life" 2018-07-18 02:51:35 +00:00			`then you could potentially get a few more hours of life if your CPU-hungry browser`
README: Fix a typo 2018-07-09 13:39:51 +00:00			`is running somewhere else on mains electricity.`
Don't use `--new-instance`, `-P` when launching FF 2018-01-24 02:59:57 +00:00
Update README.md Fixed Headings in README 2017-05-24 20:30:23 +00:00			`## Installation`
Added license and updated README 2016-05-21 09:38:46 +00:00
devops: Update release process for Github 2022-07-18 16:58:27 +00:00			`Download a binary from the [releases](https://github.com/browsh-org/browsh/releases) (~11MB).`
			`You will need to have [Firefox](https://www.mozilla.org/en-US/firefox/new/) already installed.`
Start noting good/bad terminals. Add instructions for running other apps 2016-05-23 06:57:46 +00:00
Extra loggina and README updates 2018-06-23 09:16:12 +00:00			`Or download and run the Docker image (~230MB) with:`
Auto remove container after it exits 2018-07-12 00:01:12 +00:00			`docker run --rm -it browsh/browsh`
Move integration tests to Golang CLI client After moving to Tcell and implementing its screen diff updates, we can no longer watch STDOUT to get frames during integration tests. Instead we need to use Tcell's SimulationScreen and which has a GetContents() method. This is actually also a much more robust way of being able to see what Browsh actually outputs during testing. 2018-02-17 05:52:03 +00:00
First draft of integration tests 2018-01-23 04:28:56 +00:00			`## Usage`
			`Most keys and mouse gestures should work as you'd expect on a desktop`
			`browser.`
Start noting good/bad terminals. Add instructions for running other apps 2016-05-23 06:57:46 +00:00
Update README.md Changed "Why?" to "Why use Browsh?" Removed avoidable phrases such as "that" and "and uses that" Divided a run-on sentence by using a period Switched "Firefox =>57" to "Firefox 57 (or higher) Shortened the documentation sentence and link 2018-07-15 09:04:26 +00:00			`For full documentation click [here](https://www.brow.sh/docs/introduction/).`
Added screenshot feature: press ALT+P In the endless struggle to squash a Travis-specific bug, we now have screenshots. Currently the screenshots are of the custom block font state, so you can't read the text. But I'm planning on changing the default state of the page to use a normal font - such that the frame builder needs to toggle the block font on to build a frame. This will make it more likely that screenshots will contain actual text. 2018-02-01 07:37:38 +00:00
			`## Contributing`
chore: Update README 2022-07-17 01:36:30 +00:00			`_Note that some of these instructions may be out of date (July 2022)_`

			`For generic Linux systems you can follow [this guide](https://github.com/browsh-org/browsh/blob/master/SETUP_DEV_LINUX.md) on how to setup a build environment, that you may be able to adapt for other systems as well.`

			`Windows users can follow [this guide](https://github.com/browsh-org/browsh/blob/master/SETUP_DEV_WIN.md) in order to set up a build environment.`

			`Mac users may follow [this guide](https://github.com/browsh-org/browsh/blob/master/SETUP_DEV_OSX.md) that goes through the steps of setting up a build environment.`
Update README.md 2018-10-03 06:32:36 +00:00
Added community messaging. 2018-08-10 22:51:37 +00:00			`### Communication`
chore: Update README 2022-07-17 01:36:30 +00:00			`Questions about Brow.sh? Stuck trying to resolve a tricky issue? Try:`
			`- [Github Discussions](https://github.com/browsh-org/browsh/discussions)`
			`- [Gitter](https://gitter.im/browsh)`
Refactor build process to not use pre-built bins This means that there's now a canonical script that allows other distributers to build Browsh. The only caveat being that the web extension cannot be built (Mozilla only allows one signed `.xpi` per version), so it is downloaded. 2018-07-26 10:40:31 +00:00
Move integration tests to Golang CLI client After moving to Tcell and implementing its screen diff updates, we can no longer watch STDOUT to get frames during integration tests. Instead we need to use Tcell's SimulationScreen and which has a GetContents() method. This is actually also a much more robust way of being able to see what Browsh actually outputs during testing. 2018-02-17 05:52:03 +00:00			`## Tests`

Add logo to TTY startup. README updates 2018-07-06 05:06:49 +00:00			For the webextension: in `webext/` folder, `npm test`
			For CLI unit tests: in `/interfacer` run `go test src/browsh/*.go`
			For CLI E2E tests: in `/interfacer` run `go test test/tty/*.go`
Added donation link to HTML response pages 2018-07-06 05:43:53 +00:00			For HTTP Service tests: in `/interfacer` run `go test test/http-server/*.go`
Add logo to TTY startup. README updates 2018-07-06 05:06:49 +00:00
			`## Special Thanks`
			`* [@tobimensch](https://github.com/tobimensch) For essential early feedback and user testing.`
			`* [@arasatasaygin](https://github.com/arasatasaygin) For the Browsh logo.`
Move integration tests to Golang CLI client After moving to Tcell and implementing its screen diff updates, we can no longer watch STDOUT to get frames during integration tests. Instead we need to use Tcell's SimulationScreen and which has a GetContents() method. This is actually also a much more robust way of being able to see what Browsh actually outputs during testing. 2018-02-17 05:52:03 +00:00
Add donation link to README 2020-09-02 09:36:43 +00:00			`## Donating`
			`Please consider donating: https://www.brow.sh/donate`

Update README.md Fixed Headings in README 2017-05-24 20:30:23 +00:00			`## License`
Update license name in README Thanks for spotting @tobimensch! 2018-07-27 13:32:46 +00:00			`GNU Lesser General Public License v2.1`