Jovie

@jovie/cli

Jovie for AI agents. One package is a CLI, an MCP server, and an agent skill. An agent can extract public creator data from a supported social URL or give a music artist a Jovie profile from Spotify, then hand the artist a claim link. No login or API key is required.

Install

Requires Node.js 24.21 or newer (tested on 24 and 26; Node 22.13+ also runs, without proxy support). Install an exact public release globally from npm:

npm install --global @jovie/cli@26.9.16

jovie --help jovie --version

Or run without installing: npx -y @jovie/cli@26.9.16 --help.

Use npm view @jovie/cli version to confirm registry availability before an automated install. A repository build is not proof that npm has the package.

Commands

profile create returns the existing profile unchanged when one already holds that Spotify artist. Otherwise it creates an unclaimed profile. The response has profileUrl and, when unclaimed, a claimUrl. The claim URL is not an ownership token: the artist still verifies that they own the Spotify artist. Creation is anonymous and rate limited per IP.

music resolve returns provider links with provenance, ambiguity candidates, and core MusicBrainz artist facts when an exact URL relation or MBID identifies the artist. Matching names alone do not establish cross-provider identity. Social and metadata links are separate from listening links. Embedded release groups can be incomplete; releaseGroupsComplete reports that boundary.

jovie music resolve https://open.spotify.com/artist/4Uwpa6zW3zzCSQvooQNksm --json

jovie music resolve 51972833-bb04-46b7-9401-45a5ab449ebd --json jovie music resolve USABC1234567 --kind track --territory GB --json jovie music resolve "Take Me Over" --kind track --artist "Tim White" --json jovie music resolve 123456789012 --kind album --json

creator lookup is read-only and never creates or changes a Jovie profile. When a public Jovie profile already holds that channel (matched by channel identity, not a username guess), the response is {"exists":true,"username":...,"profileUrl":...} and no source page is fetched. Only YouTube channels support extraction: an unmatched YouTube channel returns {"exists":false,...} with the display name, bio, avatar URL, and public links. Unmatched Instagram, TikTok, and Linktree inputs return SOURCE_UNSUPPORTED (HTTP 422, exit 1) because Jovie does not read those pages from its servers. Use the creator's YouTube channel URL instead. Bandcamp and custom websites return UNSUPPORTED_URL (HTTP 422, exit 1); they are outside this command's supported sources. A Linktree link in a YouTube result does not imply support for extracting that Linktree page.

--json emits JSON for API responses and wraps text resources as {"content":"..."}. Failures print {"error":{...}}, and API failures carry the server's stable apiCode (for example RATE_LIMITED or ARTIST_NOT_FOUND). Successful commands exit 0, request/response failures exit 1, and invalid usage exits 2.

--help --json returns { "content": "..." }; --version --json returns { "version": "..." }.

Reads make up to three attempts with backoff for transient failures (connection resets, 502 without an error code, 503, 504, and 429 with Retry-After of 5 seconds or less). A longer Retry-After is reported, not slept through. Writes never retry automatically: a timeout may have occurred after the server committed. Report tools therefore do not advertise idempotency. Every attempt, backoff, and body read share one 30-second deadline, so no command waits longer; set JOVIE_TIMEOUT_MS (1000-120000) to change it. Bodies are capped at 1 MiB.

Errors are one line on stderr that says what to do next (for example Could not resolve jov.ie. Check your internet connection or --base-url.). Add --debug to also print the stack and cause chain; secrets are redacted either way. Closing the output pipe early (jovie docs llms | head) exits quietly.

Every command accepts --base-url for a compatible deployment origin. The value must be an http or https origin without a path, credentials, or query parameters.

Proxies

The standalone CLI and MCP server honor HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (and their lowercase equivalents) through Node's built-in proxy support on Node.js 24 and newer (Node 22 warns and connects directly). No extra Node flags are needed. Existing TLS certificate settings remain in effect. A proxy must allow the deployment host (normally jov.ie); installing the CLI does not grant network access.

Importing the JavaScript client does not change the host application's global transport settings. Configure Node's proxy support in that application or pass fetchImpl through the client options.

MCP

{ "mcpServers": { "jovie": { "command": "npx", "args": ["-y", "@jovie/cli", "mcp"] } } }

Tools: lookup_creator, create_profile, get_artist, get_artist_guide, get_openapi, get_docs, report_issue, report_feedback. server.json describes the package for the MCP registry.

Repository agents

The repo-root .mcp.json registers jovie over stdio using node packages/jovie-cli/dist/cli.js mcp. From the repository root, build the workspace CLI before starting your MCP client, and rebuild after CLI changes:

pnpm --filter @jovie/cli build

Local agents should prefer this jovie MCP server over ad-hoc curl calls to agent routes when a tool covers the task. It exercises the public product surface from the current checkout. The entry requires no login or API key and clears JOVIE_WORKER_TOKEN so inherited worker credentials cannot expose internal tools. Using the product MCP is optional; it is not a repository agent gate.

JavaScript client

import { createProfile, fetchArtist, lookupCreator } from '@jovie/cli';

const creator = await lookupCreator('https://www.youtube.com/@creator'); // or by handle: await lookupCreator('youtube:@creator'); const profile = await createProfile('https://open.spotify.com/artist/ '); const artist = await fetchArtist('artist-username');

Boundary

Public commands send no credentials, cache nothing, and send no telemetry beyond a jovie-cli/ User-Agent. profile create and report are their only writes. Reports carry only the CLI version, platform, runtime, and the fields you pass. init writes only jovie/SKILL.md into existing agent skill directories, or into --dir. Commands use Node 24 built-ins (parseArgs, fetch, readline) and have no runtime dependencies. Internal fleet commands have the separate scoped credential boundary below. The MCP server covers tools only; adopt the official SDK when resources, prompts, or HTTP transport are needed.

The repo already supplies Node 24's node:util.parseArgs, built-in fetch, AbortSignal.timeout, TypeScript, Vitest, and Biome. Internal fleet commands use the same canonical Actions contract as their REST and MCP transports.

We considered Commander/CAC (MIT, no runtime dependency), yargs (MIT but larger), oclif (extensible but disproportionate), and Python Click/Typer or Homebrew (a second runtime/distribution lane). None fits this fixed-command, TypeScript-only surface as well as the native substrate.

Decision: retain one dependency-free Node 24 CLI for public product commands and scoped internal fleet commands. Ovie remains the operator view of the same system.

Internal fleet channel

These commands require a deployed fleet transport, operator enablement, and an individually provisioned worker identity. Installing this package does not register an agent or grant company access. Public product sessions cannot authorize fleet operations.

Every command requires --profile , --idempotency-key , and --input ' '. Use a new key for each new invocation; reuse the exact key and payload only to recover the same invocation. A repeated registration key replays the original registration; it is not a presence refresh.

fleet status returns a bounded recent view plus durable terminal history. Pass {"historyAfter":0,"historyLimit":50} in --input for the first page; use history.nextCursor for subsequent pages, with a new invocation key for each page. Save the last entry's sequence to resume when more outcomes arrive. Pages respect both the requested item limit (1–100) and a response byte budget. history.pending means older hot records still need bounded archival; another status call continues that work. Every outcome remains durable during migration. Large current request lists also expose requestsNextCursor; pass it back as requestsAfter. Terminal request outcomes and receipts remain available in history after leaving the recent view. History is scoped to this worker and profile, including after credential rotation.

The founder status endpoint can inspect history with history: {workerId, after?, limit?} after the existing session/owned-profile checks. Its historyWorkers inventory lists workers with recorded history. Archival preserves invocation payload conflicts, mission/request ID reservations, lease issuance bindings and provider-recovery evidence. It does not prune live leases or pending external operations. Genuine live capacity limits still fail closed.

The operator supplies JOVIE_WORKER_TOKEN through the runtime's secret manager. Never pass it as a CLI argument, put it in a report, or share it between workers. The CLI sends it only to the selected fleet endpoint over HTTPS (HTTP is allowed only on loopback), refuses redirects, and does not persist it. Ordinary public commands do not send it. Fleet MCP tools are exposed only when the credential is present; the server independently authenticates and authorizes every request.

Provisioning, rotation, revocation, direct mission admission and Summer delegation use the existing founder control endpoint with an exact one-use approval. Worker tokens cannot call that endpoint. Rotation preserves the worker ID, invalidates the prior token and outstanding leases, and requires the new runtime to register again. Only the configured founder can grant or revoke Summer delegatio