Surfs up!
cli-surf is a real time ocean data and forecasting service used in the command line.
Inspired by wttr.in
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 |
| show_rain_sum / srs | Show the rain sum |
| show_precipitation_prob / spp | Show the max precipitation chance |
| 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 |
| show_cloud_cover / scc | Show the hourly cloud cover |
| show_visibility / sv | Show the hourly visibility |
Examples
- Arguments are seperated by commas.
curl localhost:8000curl localhost:8000?location=new_york,hide_height,hide_wave,show_large_wavecurl localhost:8000?fc=3,hdate,loc=trestles
For detailed information you can access the help page
curl localhost:8000/help
To use cli-surf, clone the project locally and install the necessary dependencies via poetry.
-
Install Poetry.
-
Clone the repository.
git clone https://github.com/ryansurf/cli-surf.git cd cli-surf -
Install dependencies and Activate the virtual environment.
make install
-
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
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.
-
Install Docker.
-
Install Docker Compose.
-
Clone the repository.
git clone https://github.com/ryansurf/cli-surf.git cd cli-surf -
Docker compose up.
docker compose up -d # Alternatively, you can run the project using `Makefile` make run_docker
When running locally with Poetry, create a .env file from the .env.example file.
cp .env.example .envNote 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 |
Optional, sends a surf report to a specified email.
You will need to setup an email account that is able to utilize SMTP services. Gmail can be used, 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_dockerNote that the Flask server must be running in order to send emails.
Although this application was made with the cli in mind, there is a frontend.
Streamlit Frontend
Streamlit is used!
To run streamlit: streamlit run src/dev_streamlit.py
You will be able to find the frontend here: http://localhost:8502
HTML/JS/CSS Frontend
Note
Streamlit is now the main focus for the frontend. This legacy frontend is no longer being actively developed.
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!
cli-surf can generate personalized surf reports using OpenAI's GPT models. This section is for those that choose to not rely on gpt4free as the repo faces pending legal action.
Enabling GPT Reports
-
Obtain an OpenAI API Key:
- Sign up at OpenAI.
- Navigate to the API section and create a new API key.
- Make sure to add a payment method.
-
Update
.envFile:GPT_PROMPT=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_here GPT_MODEL=gpt-3.5-turbo # Or use gpt-4 for better results -
Use the GPT Argument::
- Example Usage:
curl localhost:8000?location=Malibu,gptCustomizing the GPT Prompt You can tailor the response by changing the GPT_PROMPT in your .env file to get different types of reports.
- Common Examples:
GPT_PROMPT="Analyze the surf conditions and suggest the best time of day to surf."GPT_PROMPT="What are some good places to eat around this surf spot"
Notes on Usage
- Common Issue: Without a payment method, this feature will not work as OpenAI will deny API requests from these accounts.
- API Costs: Using the GPT feature will consume tokens from your OpenAI account based on the size of your custom prompt and the responses.
- Response Time: Generating GPT responses may take longer than standard outputs, especially if there are outages.
- Model Selection: Using gpt-4 provides better results but may be slower and more expensive than gpt-3.5-turbo.
Thank you for considering contributing to cli-surf!
See CONTRIBUTING.md to get an idea of how contributions work.
Questions? Comments?
