cli-surf 2.5.1

cli-surf is a real-time ocean data and surf forecasting tool for the command line.

• Live wave height, swell direction, period, UV index, wind, and more
• Real-time tide level with direction indicator and next tide extreme (via NOAA)
• Sea surface temperature
• Forecasts up to 7 days out
• Use as a CLI tool (surf) or query via HTTP API / browser
• Optional GPT-powered surf reports (includes tide and sea temp context)
• Supports metric and imperial units, custom colors, and JSON output

Inspired by wttr.in · Documentation · Discord

Table of Contents

• Usage
• Setup
  • Poetry
  • Docker
  • Environment Variables
  • Email Server
  • MongoDB
• GPT Surf Report
• Tech Stack
• Architecture
• Contributing
• Contributors

💻 Usage

There are several ways to use cli-surf: install it as a CLI tool via pipx, hit the public API, or run the server locally and access it via API/browser.

Installing via pipx (pypi)

brew install pipx
pipx install cli-surf

surf --help
surf --location scripps_pier --forecast 4

Hitting the public API

curl https://api.clisurf.com

Running the server locally and using via API

Start the server locally (see Setup below), then query it from your browser or CLI:

$ curl localhost:8000

Location:  San Diego

      .-``'.
    .`   .`
_.-'     '._

UV index:  6.4
Wave Height:  3.9
Wave Direction:  238.0
Wave Period:  9.8
Sea Surface Temp: 64.8
Tide: 3.2 ft ↑ | Next High: 5.1 ft @ 14:30 UTC

API Examples

Arguments are separated 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,c=light_blue
curl localhost:8000?show_past_uv,show_height_history,show_direction_history,show_period_history
curl localhost:8000?loc=malibu,gpt,color=yellow
curl localhost:8000?loc=nazare,json

For the full argument reference, see below or run:

curl localhost:8000/help

API Arguments

Display

Surf Conditions

Historical Data

GPT

🛠️ Setup

How to Start Locally with 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. Start the server.

   poetry run python src/server.py
   
   # Or via Makefile
   make run
   

How to Start with Docker

1. Install Docker and Docker Compose.

2. Clone the repository.

   git clone https://github.com/ryansurf/cli-surf.git
   cd cli-surf
   

3. Start the container.

   docker compose up -d
   
   # Or via Makefile
   make run_docker
   

Variables

When running locally with Poetry, create a .env file from the example:

cp .env.example .env

When starting with Docker, the .env file is created automatically from .env.example during the image build.

General

Email (optional — see Email Server)

GPT (optional — see GPT Surf Report)

Database (optional — see MongoDB)

Email Server

Optional — sends a surf report to a specified email on a schedule.

You'll need an email account with SMTP access. Gmail works; follow Method #1 here, then update the email variables in .env.

Note: The FastAPI server must be running to send emails.

# Send email locally (Poetry)
make send_email

# Send email via Docker
make send_email_docker

MongoDB

Optional — stores all request output in a MongoDB database.

See the MongoDB get started guide for setup, then set DB_URI in your .env.

Frontend

streamlit run src/dev_streamlit.py
# Available at http://localhost:8502

🧠 GPT Surf Report

cli-surf can generate personalized surf reports using OpenAI's GPT models.

Setup

1. Get an OpenAI API key at platform.openai.com. Make sure a payment method is added.

2. Update .env:

   API_KEY=your_openai_api_key_here
   GPT_MODEL=gpt-3.5-turbo   # gpt-4o recommended for better results
   GPT_PROMPT=With this data, recommend what size board I should ride and nearby surf spots that may be better with the given conditions.
   

3. Use the gpt argument:

   curl localhost:8000?location=Malibu,gpt
   

Customizing the prompt

Change GPT_PROMPT in .env to get different types of reports:

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

• A payment method is required — OpenAI will reject requests from free accounts.
• GPT responses consume tokens based on prompt and response size.
• Response time may be slower than standard output, especially during OpenAI outages.
• gpt-4o gives better results than gpt-3.5-turbo but costs more.

🔧 Tech Stack

📐 Architecture

Architecture

📈 Contributing

Thank you for considering contributing to cli-surf!

See CONTRIBUTING.md to get started.

Questions? Comments?

• Discord
• Discussions
• GitHub

✨ 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 💻
Latif Fetahaj 💻 ⚠️	Kim ⚠️ 💻	Devon Hebenton 💻	AristosKass ⚠️	Raza Khan 💻

License