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. Packages print as a table with each id, name, description, version, release date and price. Bundles get a table of their own listing what is inside them, since a bundle is a priced set of packages rather than a package.

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; naming more than one picks the most mature of them and says so. Anything already present is skipped rather than overwritten, so re-running the command is safe.

Once the download is unpacked, each installed additive runs the install() routine from the Interaction chapter: its own required additives are resolved and pulled, its extract files land in your app and its pip packages are installed. A dependency that has dependencies of its own is followed through, and nothing is visited twice. So one wf ocean install -a portal can quietly bring in the base it extends and the two additives it talks to.

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), and the price — extensions must carry one, additives may be free. It then builds an archive, uploads it with a SHA-256 checksum the hub verifies, and reports the published id back to you. If the package has no license yet, it searches the hub's license catalog with you, asks for whatever placeholders the license needs (your name, the year) and applies it.

The archive is built from your working directory, minus the obvious junk (.git, __pycache__, node_modules, editor folders, compiled files) and minus everything your .gitignore excludes — nested ones included, negations honoured. So the .gitignore that wf create additive writes for you is doing double duty: it keeps your repository clean and it decides what ships.

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 OCEAN_AUTH environment variables. (AUTH_API was the alpha spelling of the second one and is no longer read.)

Continue reading

From here you can continue straight with the Reference overview.