Foleo CLI

Publish and manage Markdown documents and trusted active-HTML artifacts through Foleo Publish.

Requirements

• macOS
• Node.js 22 or later
• An invited Foleo Publish account

Sign in

npx -y @foleo/cli login
npx -y @foleo/cli whoami
npx -y @foleo/cli doctor

The default key can read, publish, unpublish, and delete or restore artifacts — delete is reversible, holding the bytes for a 30-day restore window. Only irreversible purge uses incremental authority: add --allow-purge at login when you intentionally need it. Purge is never requested by a normal installation. --allow-delete is retired and accepted silently, so existing scripts keep working.

That runs npm latest with no global install, which is the intended steady state — there is no need to install anything permanently. Optional: npm install --global @foleo/cli puts foleo on PATH.

npx -y @foleo/cli skill get prints the version-matched bundled skill to stdout — it installs nothing. To keep it across sessions, write that output wherever your agent loads reusable skills or instructions from. skill path prints where that file lives on disk, which is only a stable location under a global install — under npx it resolves inside a temporary cache. Agents can read the live contract at https://foleo.app/agents.md, also available as https://foleo.app/CLAUDE.md. Foleo also runs a remote MCP server at https://mcp.foleo.app/mcp.

npx -y @foleo/cli --version reports which CLI you are running, and doctor --json includes it as cliVersion. npx resolves npm latest on each run, so it stays current on its own; a global install stays pinned until you reinstall. doctor also compares your version against the public npm registry and warns if a newer one exists — an unauthenticated GET with a 2.5s timeout that fails open, so a slow or unreachable registry never blocks setup. Set FOLEO_SKIP_UPDATE_CHECK=1 to turn it off; no other command touches the network except the Foleo API.

Production is the default. Use --staging on any command for a staging rehearsal, or run npx -y @foleo/cli environment --staging to verify the selected API. FOLEO_API_BASE remains an explicit custom override.

Artifact discovery and lifecycle

npx -y @foleo/cli list --json
npx -y @foleo/cli list --kind document --format markdown --json
npx -y @foleo/cli get <id> --json
npx -y @foleo/cli status <id> --json
npx -y @foleo/cli unpublish <id> --revision <etag> --json
npx -y @foleo/cli delete <id> --revision <etag> --json
npx -y @foleo/cli restore <id> --revision <deletion-etag> --json
npx -y @foleo/cli purge <id> --revision <etag> --confirm <id> --json
npx -y @foleo/cli deletion-status <id> --json

These commands are artifact-generic: the server resolves source format from the id. unpublish is reversible, timerless, and byte-preserving. delete takes the artifact offline and starts a 30-day restore window; it never deletes local user files. purge skips that window but remains asynchronous. A 202 response is acceptance, not proof of erasure—only deletion-status state complete confirms that Foleo-held bytes are gone. Always carry the returned opaque etag exactly.

Markdown publishing

npx -y @foleo/cli publish ./notes.md --json
npx -y @foleo/cli update <id> ./notes.md --revision <etag> --json

Source-aware creates refuse an owner-scoped exact content match instead of silently creating a duplicate. Reconnect/update the returned artifact id, or only when a distinct page is intentional repeat the create with --publish-separately.

Trusted HTML alpha

HTML is executable content. A human must inspect the local source and explicitly approve the hosting risk before an agent uses the acknowledgement flag. The pre-PSL friends alpha accepts a static site rooted at index.html, including additional HTML pages and allowlisted local assets. Use no sensitive information.

npx -y @foleo/cli publish ./site --accept-hosting-risk --json
npx -y @foleo/cli publish ./site --accept-hosting-risk --settings '{"visibility":"password"}' --password-stdin --json
npx -y @foleo/cli update <id> ./site --revision <etag> --json
npx -y @foleo/cli settings <id> --json
npx -y @foleo/cli settings <id> --set visibility=private --revision <etag> --json
npx -y @foleo/cli limits --json

--runtime-profile auto|open|contained chooses the HTML runtime profile on an HTML publish or update (auto when omitted); an explicit contained page that does not fit fails with contained_profile_unavailable and its blocked references, and is never retried as open. A change that exposes an existing artifact to more readers or adds a working address (private to unlisted, restore, name attach, a keep-as-alias rename) needs --acknowledge-access-widening, passed only after the human approves that change; without it the API answers acknowledgement_required. The flag is never implied by --accept-hosting-risk.

publish infers Markdown vs HTML from the path. The six html-* commands remain deprecated aliases. Carry the latest returned opaque etag into generic update and settings mutations, and the latest stateRevision into those aliases. Public HTML is not available during this alpha. No html-delete, html-restore, or html-purge commands exist.

The CLI stores its credential in macOS Keychain after login, and logging in again revokes the key it replaces. npx -y @foleo/cli logout revokes that key and removes it — if the revoke fails, it still removes it and exits with an error; --no-revoke only removes it from this machine. Neither touches FOLEO_TOKEN. Signing in to the Mac app does not sign in the CLI. Never write credentials into source files, prompts, artifacts, or repositories. See https://foleo.app/agents.md for the concise agent contract.