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 — and its first column is the bundle's own id, zero padded to six digits. Remember that number; the installer takes it.

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.

Bundles, and channels that describe an intention

Naming a package at a time stops being pleasant once a vendor ships six of them that belong together. That is what a bundle is for, and --bundle / -b takes its id. It is not a special install mode: the bundle is resolved through the Ocean and expands into exactly the -a and -e list it stands for, so bundles and single packages mix in one command:

terminal bash

# Everything the bundle contains
wf ocean install -b 000123

# A bundle plus one package it does not include
wf ocean install -b 123 -a portal

# ...and a pin still wins over the bundle's own entry
wf ocean install -b 123 -a portal==1.2.0

Leading zeros are optional. A package that turns up twice — in two bundles, or in a bundle and behind an explicit flag — is installed once and reported as a duplicate, and an explicit id==version beats the bundle's unpinned entry. A bundle id that resolves to nothing is reported and skipped; the rest of the install carries on.

The other two new flags are about the kind of release you want rather than a specific channel. --pre / -p says "the newest prerelease, whatever it happens to be" — a package sitting at 1.1rc1 gives you the candidate, one still at 1.1b2 gives you the beta. --prefer-stable / -ps says the opposite: take the stable release, and only fall back to a prerelease if there is no stable one at all. They compose with the channel flags, so -ps --beta reads as "stable, else the latest beta".

Combining -p with anything more specific is not an error, it is just redundant — and the CLI tells you so in yellow rather than silently picking one. That is the house style for every flag conflict in wf: resolve it, then say out loud what was resolved.

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.