Skip to content

Latest commit

 

History

History
204 lines (142 loc) · 7 KB

README.md

File metadata and controls

204 lines (142 loc) · 7 KB
Raw

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

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

cli-surf_website gif

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?

✨ Contributors

License

License