ryansurf/cli-surf - Githubissues

GitHub last commit

Surfs up!

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

Inspired by wttr.in

💻 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

cli-surf gif

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
show_past_uv / spuv	Show past uv index
hide_past_uv	Hide past uv index
show_height_history / shh	Show past wave height index
hide_height_history	Hide past wave height index
show_direction_history / sdh	Show past wave direction index
hide_direction_history	Hide past wave direction index
show_period_history / sph	Show past wave period index
hide_period_history	Hide past wave period 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:8000
curl localhost:8000?location=new_york,hide_height,hide_wave,show_large_wave
curl localhost:8000?fc=3,hdate,loc=trestles
curl localhost:8000?show_past_uv,show_height_history,show_direction_history,show_period_history

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.

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

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.

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

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. 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_docker

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

Frontend

cli-surf_website gif

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!

🧠 GPT Surf Report

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 .env File:

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,gpt
```

Customizing 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.

📈 Contributing

Thank you for considering contributing to cli-surf!

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

Questions? Comments?

✨ Contributors

_{Ryan Frederich} 💻 📖 ⚠️ 🤔 💬	_𝕂' 💻 📖 ⚠️ 🤔 💬	_{Corey L.} 💻	_{Shaiful Azhar} 💻	_Hummus-Ful 🚇	_Rajiv-Rago 💻	_{Ulises-Sanch3z} 💻
_{Andrew Koller} 💻	_{Michael McGrain} 💻	_SeanAverS 💻	_{Rabel Mervin} 💻	_{Vaibhav Chouhan} 💻	_{Nandani Thakur} 💻	_Brandon 🚇
_{ChristianToro} 💻 🐛	_{Myles B.} 💻	_{Balaji Ganapathy} 🐛	_{chengjackjelly} 🚇	_{Varun Singh} 📖	_macnult 💻	_AITMAR-TAFE 💻