CLI

Ocean

Additives and extensions become really powerful once you can share them. The Ocean is WebFluid's package hub, and wf ocean is the client that talks to it: search for packages, install them into your project, and publish your own.

Logging in

Browsing and installing open-source packages works anonymously. Anything tied to an account — paid packages you own, or publishing — needs a token. You generate one on the Ocean and paste it into wf ocean login, which validates and stores it in ~/.wf-ocean. wf ocean logout removes it again.

terminal bash

wf ocean login      # paste your Ocean token when prompted
wf ocean logout     # forget the stored token

Searching

wf ocean search takes an optional query and a few filters. Without any type flag it searches additives, extensions and bundles alike:

terminal bash

# Everything matching 'auth'
wf ocean search auth

# Only additives, open-source ones
wf ocean search dashboard --additives --oss-only

# Only extensions
wf ocean search -e stripe

The type flags are --additives / -a, --extensions / -e and --bundles / -b; --oss-only and --paid-only narrow by licensing. Results print as a table with each package's id, version, release date and price.

Installing

wf ocean install pulls packages into your project. You name additives with --additive / -a and extensions with --extension / -e; both flags are repeatable and accept a pinned version with id==version. Additives land in additives/<id>, extensions in extensions/<id> (and are installed editable with pip):

terminal bash

# One additive and one extension
wf ocean install -a portal -e stripe

# A pinned additive version
wf ocean install -a portal==1.2.0

# Resolve the latest prerelease instead of the stable channel
wf ocean install -a portal --alpha

By default install resolves the latest stable release. The --alpha, --beta and --rc flags switch the channel when you want a prerelease. When an installed additive declares required additives in its manifest, those are resolved and pulled in for you as well.

Paid packages require you to be logged in and to own them (you purchase them on the Ocean). Because installing paid digital content starts its delivery, the CLI asks you to waive your right of withdrawal before it downloads — open-source packages skip that entirely.

Publishing

wf ocean publish uploads the package in your current directory. It figures out what it is from the files it finds: a manifest.json makes it an additive, a pyproject.toml makes it an extension. You must be logged in, and the package needs an id (its manifest id, or the project name in pyproject.toml):

terminal bash

cd additives/portal
wf ocean publish

Publish walks you through the rest interactively: which maintainer to publish as (your personal account or one of your organisations), the price (extensions must carry one; additives may be free), and — the first time — a license. It then builds a compressed archive, uploads it with an integrity checksum, and reports the published id back to you.

The wf ocean client targets the public Ocean at ocean.webfluid.dev by default. If you run your own hub, point it elsewhere with the OCEAN_API and AUTH_API environment variables.

Continue reading

From here you can continue straight with the Reference overview.