Moana CLI

Self-service command-line interface for Media Moana — manage media, folders, and AI processing from the terminal.

Installation

npm install -g moana-cli

Requires Node.js 20+. Run without installing via npx moana-cli.

Quick Start

moana login                          # browser-based authentication
moana folder list                    # list your folders
moana media upload ./photo.jpg       # upload a file

Run moana --help to see all commands, or moana <command> --help for command-specific options.

Configuration

Config is stored at ~/.moana/config.yml.

Output Formats

Most commands accept --output json|yaml|table (table is the default for list commands). All formats are syntax-highlighted.

Development

git clone https://github.com/mediamoana/moana-cli.git
cd moana-cli
npm install
npm link              # makes the `moana` binary available locally

When you're done, unlink it to restore the published moana (or remove it entirely):

npm unlink -g moana-cli

Useful scripts:

npm start -- folder list
npm run lint
npm run lint:fix
npm run format

Publishing

Maintainer notes — for releasing new versions of moana-cli to npm.

First time only: run npm login for the browser auth flow.

Releasing a new version

# 1. Bump version — pick one based on the change
npm version patch    # 1.0.0 → 1.0.1   bug fix
npm version minor    # 1.0.0 → 1.1.0   backward-compatible feature
npm version major    # 1.0.0 → 2.0.0   breaking change
# This updates package.json, creates a commit, and tags it vX.Y.Z

# 2. Publish to npm
npm publish --dry-run        # sanity-check the tarball (runs lint gate)
npm publish                  # `publishConfig.access: public` is set in package.json

# 3. Push commit + tag
git push && git push --tags

# 4. Verify
npm view moana-cli version
npx moana-cli@latest --help

To release a pre-release without claiming latest:

npm version prerelease --preid=beta   # e.g. 1.1.0 → 1.1.1-beta.0
npm publish
git push && git push --tags
npm dist-tag add [email protected] beta
# Users install with: npm i moana-cli@beta

Unpublishing and deprecating

You cannot republish over an existing version. npm publish against a version that already exists fails with 403, and unpublishing does not free the version number — it stays permanently reserved. Always bump the version instead.

Unpublish — only works within 72 hours of publishing. After that, npm only allows it under strict conditions (no dependents, low download count, sole maintainer) and usually requires contacting npm support.

npm unpublish [email protected]     # specific version
npm unpublish moana-cli --force   # entire package

Deprecate — the recommended way to retire a bad version. It doesn't remove the package, but anyone installing it sees your warning. Reversible by passing an empty string.

npm deprecate [email protected] "Has a bug, upgrade to 1.0.2"
npm deprecate [email protected] ""    # undo

Typical recovery flow when a release is broken: publish a fixed version, then deprecate the bad one.

License

MIT