@agent-journal/cli

NPM wrapper for the Agent Journal member CLI.

Install

npm install -g @agent-journal/cli

If global install fails with EACCES, configure npm to use a user-owned prefix and add its bin directory to PATH instead of using sudo npm install.

Use

agent-journal init --base-url https://your-service.example <invite_code>
agent-journal start
agent-journal status

For local debugging:

agent-journal run

To stop and remove the background agent:

agent-journal uninstall

After a manual npm upgrade, restart the background service so it points at the managed runtime under ~/.agent-journal/current:

npm install -g @agent-journal/cli@latest
agent-journal restart
agent-journal status

To check or apply a managed update published by the service:

agent-journal update --check
agent-journal update --apply

--apply downloads the selected artifact, verifies its sha256 and signature, installs it under ~/.agent-journal/versions/<version>, switches ~/.agent-journal/current, and restarts the managed service when one is installed.

If the service rollout has auto apply disabled, the background agent records the available update and agent-journal status prints the target version; it will not download or execute the artifact until agent-journal update --apply runs.

Publishing

The production publishing path is GitHub Actions Trusted Publishing. Configure the npm package trusted publisher with:

• Package: @agent-journal/cli
• Publisher: GitHub Actions
• Repository owner: Bloomingg
• Repository name: agent-journal
• Workflow filename: client-release.yml
• Environment: empty unless the workflow is later bound to a GitHub environment

Then manually run the Client Release workflow. The workflow builds the vendored binaries with AGENT_JOURNAL_UPDATE_PUBLIC_KEY, generates the signed service release manifest with AGENT_JOURNAL_UPDATE_PRIVATE_KEY_PEM, publishes the npm package through OIDC, runs an npm tarball smoke test on Linux, macOS, and Windows, uploads update artifacts, and registers release metadata with the Agent Journal service through AGENT_JOURNAL_CLIENT_RELEASE_SECRET.

The npm package is only the first-install bootstrap. After CI registers a release, use Admin Release Center to publish it to dev, beta, or stable and control rollout percentage, auto apply, forced update, pause, and rollback.

Release versions are immutable after publication. If npm publish or GitHub Release upload has already succeeded for the same version, rerun the workflow with publish_to_npm=false; it will reuse the existing GitHub Release manifest for service registration. For any artifact/content change, bump packages/agent-journal/package.json before running the workflow again.

Local commands are for dry-run checks only:

set -a
source ../../.env.update-signing
set +a
unset AGENT_JOURNAL_UPDATE_PRIVATE_KEY_PEM
npm test
npm run build:binaries
npm pack --dry-run --ignore-scripts

The npm package only needs AGENT_JOURNAL_UPDATE_PUBLIC_KEY. Do not leave AGENT_JOURNAL_UPDATE_PRIVATE_KEY_PEM in the environment for npm publish; the private key is only needed when generating a signed service release manifest.

The CI publish step uses npm publish --ignore-scripts after a single explicit binary build. This avoids prepack rebuilding the npm package binaries after the signed release artifacts have already been generated.

Set AGENT_JOURNAL_UPDATE_PUBLIC_KEY when building release binaries so managed updates can verify service-provided artifact signatures:

AGENT_JOURNAL_UPDATE_PUBLIC_KEY="<base64-ed25519-public-key>" npm run build:binaries

After uploading the built binaries to release storage, generate the service registration payload:

set -a
source ../../.env.update-signing
set +a
AGENT_JOURNAL_ARTIFACT_BASE_URL="https://updates.example.com/agent-journal/0.1.0" \
npm run release:manifest

The generated dist/release-manifest.json can be POSTed to /api/v1/admin/client-releases. The script also copies release-named binaries to dist/artifacts/ so CI can upload files whose names match the manifest URLs.

release:local runs the npm wrapper tests, builds the vendored binaries with package version, git commit, UTC build time metadata, and the optional update public key, then performs an npm pack --dry-run.

The package includes binaries for macOS arm64/x64, Windows x64, and Linux x64.