Surfs up!

cli-surf is a real time ocean data and forecasting service used in the command line.

Inspired by wttr.in

Documentation | Discord

💻 Usage

Using your browser or command-line interface you can access the service.

$ curl localhost:8000

Location:  San Diego

      .-``'.
    .`   .`
_.-'     '._ 
        
UV index:  6.4
Wave Height:  3.9
Wave Direction:  238.0
Wave Period:  9.8

Arguments

Argument	Description
location / loc	Specify the location of your forecast. Ex: location=new_york_city or location=nyc.
forecast / fc	Number of forecast days. Max = 7, default = 0
hide_wave / hw	Hide the default wave art
show_large_wave / slw	Show the large wave art
show_air_temp / sat	Show the air temp
show_wind_speed / sws	Show the wind speed
show_wind_direction / swd	Show the wind direction
hide_uv / huv	Hide uv index
hide_height / hh	Hide surf height
hide_direction / hdir	Hide Swell direction
hide_period / hp	Hide swell period
hide_location / hl	Hide location
hide_date / hdate	Hide date in forecast
metric / m	Numbers in Metric units. Defaults to Imperial
decimal / dec	Specify decimal points in output
color / c	Choose color of wave art. Ex: color=light_blue
json / j	Output the data in JSON format. Must be the only argument
gpt / g	Activates the GPT surf report. Change the GPT_PROMPT variable in .env to customize responses. Default = off

Examples

• Arguments are seperated by commas.
• curl localhost:8000
• curl localhost:8000?location=new_york,hide_height,hide_wave,show_large_wave
• curl localhost:8000?fc=3,hdate,loc=trestles

For detailed information you can access the help page

• curl localhost:8000/help

🛠️ Setup

How to Start Locally with Poetry

To use cli-surf, clone the project locally and install the necessary dependencies via poetry.

1. Install Poetry.

2. Clone the repository.

   git clone https://github.com/ryansurf/cli-surf.git
   cd cli-surf

3. Install dependencies and Activate the virtual environment.

   make install

4. Run the project. For example, if the entry point is server.py, use the following command.

   python src/server.py
   
   # Alternatively, you can run the project using `Makefile`
   make run

How to Start with Docker

If you do not have Poetry installed or do not want to pollute your local environment, you can also start the project using Docker Compose.

1. Install Docker.

2. Install Docker Compose.

3. Clone the repository.

   git clone https://github.com/ryansurf/cli-surf.git
   cd cli-surf

4. Docker compose up.

   docker compose up -d
   
   # Alternatively, you can run the project using `Makefile`
   make run_docker

Variables

When running locally with Poetry, create a .env file from the .env.example file.

cp .env.example .env

Note that when starting with Docker, the .env file will be automatically created from .env.example during the image build.

Variable	Description
PORT	The port you want to open to run the application. Default = 8000
IP_ADDRESS	The ip your server is running on. Default = localhost
SMTP_SERVER	The email server you are using. Default = smtp.gmail.com
SMTP_PORT	The email server port you are using. Default = 587
EMAIL	The email you will send the report from.
EMAIL_PW	The sending email's password
EMAIL_RECEIVER	The email that will receive the report (your personal email)
COMMAND	The command that will be ran and shown in the email. Default = localhost:8000
SUBJECT	The email's subject. Default = Surf Report
GPT_PROMPT	Given the surf data (height, swell direction, etc.), you can tell the GPT what kind of report you would like. For example: With this data, recommend what size board I should ride and nearby surf spots that may be better with the given conditions.
API_KEY	Your OpenAI API key. Optional, the default GPT does not need an API key (and has slighly worse performance). Create one here
GPT_MODEL	The OpenAI GPT model. Default = gpt-3.5-turbo (if possible, using gpt-4o is recommended.) Explore other models here

Email Server

Optional, sends a surf report to a specified email.

You will need to setup an email account that is able to utilize SMTP services. I used Gmail, following Method #1 outlined here. After doing this, change the variables in .env

The Email Server can be executed using one of the following methods.

# Send Email locally using Poetry
make send_email

# Send Email in a Docker container
make send_email_docker

Note that the Flask server must be running in order to send emails.

Frontend

Although this application was made with the cli in mind, there are two frontends (experimenting at the moment).

HTML/JS/CSS Frontend

http://localhost:8000/home or <ip_of_host>:<port>/home if the application is running on a different host or you have changed the default port.

You may need to change IP_ADDRESS in .env to match the ip of the host running the machine.

Now, running python3 server.py will launch the website!

Streamlit Frontend

Streamlit is also an option that we are experimenting with.

To run streamlit: streamlit run src/dev_streamlit.py

You will be able to find the frontend here: http://localhost:8502

📈 Contributing

Thank you for considering contributing to cli-surf!

See CONTRIBUTING.md to get an idea of how contributions work.

Questions? Comments?

• Discord
• Discussions
• GitHub

✨ Contributors

License