Metadata-Version: 2.4
Name: cli-surf
Version: 0.1.0
Summary: Command-line surf report tool
License: MIT
License-File: LICENSE
Keywords: surf,weather,ocean,cli,terminal
Author: ryansurf
Author-email: your@email.com
Requires-Python: >=3.10
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Dist: cachetools (>=7.0.5,<8.0.0)
Requires-Dist: curl-cffi (>=0.7.1,<0.8.0)
Requires-Dist: debugpy (>=1.8.20,<2.0.0)
Requires-Dist: email-validator (==2.1.1)
Requires-Dist: fastapi (>=0.135.2,<0.136.0)
Requires-Dist: flask (==3.0.3)
Requires-Dist: flask-cors (==5.0.0)
Requires-Dist: g4f (==0.3.2.2)
Requires-Dist: geopy (==2.4.1)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: matplotlib (==3.9.0)
Requires-Dist: numpy (>=1.26.4,<2.0.0)
Requires-Dist: openai (>=1.30.5,<2.0.0)
Requires-Dist: openmeteo-requests (==1.2.0)
Requires-Dist: pandas (==2.2.2)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: pydantic-settings (==2.2.1)
Requires-Dist: pymongo[gssapi,snappy,srv,tls] (>=4.15.4,<5.0.0)
Requires-Dist: python-dotenv (==1.0.1)
Requires-Dist: requests (==2.32.4)
Requires-Dist: requests-cache (==1.2.0)
Requires-Dist: retry-requests (==2.0.0)
Requires-Dist: seaborn (>=0.13.2,<0.14.0)
Requires-Dist: streamlit (>=1.35.0,<2.0.0)
Requires-Dist: streamlit-folium (>=0.22.0,<0.23.0)
Requires-Dist: uvicorn (>=0.42.0,<0.43.0)
Project-URL: Homepage, https://github.com/ryansurf/cli-surf
Project-URL: Repository, https://github.com/ryansurf/cli-surf
Description-Content-Type: text/markdown

![pytest](https://github.com/ryansurf/cli-surf/actions/workflows/pytest.yml/badge.svg)
![linter](https://github.com/ryansurf/cli-surf/actions/workflows/linter.yml/badge.svg)
[![codecov](https://codecov.io/github/ryansurf/cli-surf/graph/badge.svg?token=N8CAIUXMJG)](https://codecov.io/github/ryansurf/cli-surf)
![GitHub last commit](https://img.shields.io/github/last-commit/ryansurf/cli-surf)

Surfs up!

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

Inspired by [wttr.in](https://github.com/chubin/wttr.in)

[Documentation](https://ryansurf.github.io/cli-surf/) | [Discord](https://discord.gg/He2UpxRuJP)

## 💻 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](https://github.com/ryansurf/cli-surf/blob/main/help.txt) 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](https://python-poetry.org/docs/#installation).

2. Clone the repository.
    ```bash
    git clone https://github.com/ryansurf/cli-surf.git
    cd cli-surf
    ```

3. Install dependencies and Activate the virtual environment.
    ```bash
    make install
    ```

4. Run the project. For example, if the entry point is `server.py`, use the following command.
    ```bash
    poetry run 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](https://docs.docker.com/engine/install/).
2. Install [Docker Compose](https://docs.docker.com/compose/install/).

3. Clone the repository.
    ```bash
    git clone https://github.com/ryansurf/cli-surf.git
    cd cli-surf
    ```

4. Docker compose up.
    ```bash
    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.
```bash
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](https://platform.openai.com/api-keys) |
| `GPT_MODEL`  | The OpenAI GPT model. Default = `gpt-3.5-turbo` (if possible, using `gpt-4o` is recommended.) Explore other models [here](https://platform.openai.com/docs/overview)|
| `DB_URI`  | MongoDB URI |


### 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](https://www.cubebackup.com/blog/how-to-use-google-smtp-service-to-send-emails-for-free/). After doing this, change the variables in `.env`

The Email Server can be executed using one of the following methods.
```bash
# 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.

### MongoDB

Optional, stores all request output into a MongoDB database.

See [get started](https://www.mongodb.com/docs/get-started/?language=python) to learn how to set this up!

### Frontend

    cli-surf_website gif

Although this application was made with the cli in mind, there is a frontend.

**Streamlit Frontend**

[Streamlit](https://streamlit.io/) 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**

1. **Obtain an OpenAI API Key**:

   - Sign up at [OpenAI](https://beta.openai.com/signup/).
   - Navigate to the API section and create a new API key.
   - Make sure to add a payment method.

2. **Update `.env` File**:

   ```bash
   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
   ```

3. **Use the GPT Argument:**:
    - Example Usage:
  ```bash
  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:
      ```bash
        GPT_PROMPT="Analyze the surf conditions and suggest the best time of day to surf."
       ```
       ```bash
        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](https://github.com/ryansurf/cli-surf/blob/main/CONTRIBUTING.md) to get an idea of how contributions work.

Questions? Comments?

* [Discord](https://discord.gg/He2UpxRuJP)
* [Discussions](https://github.com/ryansurf/cli-surf/discussions)
* [GitHub](https://github.com/ryansurf)

## ✨ Contributors

[![All Contributors](https://img.shields.io/github/all-contributors/ryansurf/cli-surf?color=ee8449&style=flat-square)](#contributors)

       Ryan Frederich
Ryan Frederich (https://ryansurf.github.io/)
💻 📖 ⚠️ 🤔 💬
       𝕂' 
𝕂'  (https://github.com/K-dash)
💻 📖 ⚠️ 🤔 💬
       Corey L.
Corey L. (https://github.com/death12239)
💻
       Shaiful Azhar
Shaiful Azhar (https://github.com/shaifulazh)
💻
       Hummus-Ful
Hummus-Ful (https://github.com/Hummus-Ful)
🚇
       Rajiv-Rago
Rajiv-Rago (https://github.com/Rajiv-Rago)
💻
       Ulises-Sanch3z
Ulises-Sanch3z (https://github.com/Ulises-Sanch3z)
💻

       Andrew Koller
Andrew Koller (https://github.com/avkoll)
💻
       Michael McGrain
Michael McGrain (https://github.com/mrmcgrain)
💻
       SeanAverS
SeanAverS (https://github.com/SeanAverS)
💻
       Rabel Mervin 
Rabel Mervin  (https://github.com/rabelmervin)
💻
       Vaibhav Chouhan
Vaibhav Chouhan (https://github.com/vaibhav-2703)
💻
       Nandani Thakur 
Nandani Thakur  (https://github.com/NandaniThakur)
💻
       Brandon
Brandon (https://github.com/hotpocket)
🚇

       ChristianToro
ChristianToro (https://github.com/ChristianToro)
💻 🐛
       Myles B.
Myles B. (https://github.com/MylesPerHour201)
💻
       Balaji Ganapathy
Balaji Ganapathy (https://github.com/balugans)
🐛
       chengjackjelly
chengjackjelly (https://github.com/chengjackjelly)
🚇
       Varun Singh
Varun Singh (https://github.com/vsingk)
📖 🐛
       macnult
macnult (https://github.com/macnult)
💻
       AITMAR-TAFE
AITMAR-TAFE (https://github.com/AITMAR-TAFE)
💻

       Latif Fetahaj
Latif Fetahaj (https://github.com/latiffetahaj)
💻 ⚠️
       Kim
Kim (http://www.kimcodes.lol)
⚠️ 💻
       Devon Hebenton
Devon Hebenton (https://github.com/hebentod)
💻
       AristosKass
AristosKass (https://github.com/AristosKass)
⚠️
       Raza Khan
Raza Khan (https://github.com/raza-khan0108)
💻

## License
[![License](https://img.shields.io/:license-mit-blue.svg?style=flat-square)](https://badges.mit-license.org)

