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 |
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
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 using Poetry.
poetry install
-
Activate the virtual environment.
poetry shell
-
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 .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 |
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.
Although this application was made with the cli in mind, there is a 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!
Thank you for considering contributing to cli-surf!
See CONTRIBUTING.md to get an idea of how contributions work.
Questions? Comments?