One library. Every agent.

Install the CLI

Start in the browser: visit floom.dev and sign in with Google or email. When your Library opens, install the CLI:

$ npm i -g @floomhq/floom

Confirm the installed command:

$ floom --help

On Mac you can also brew install floomhq/tap/floom. For automation or AI agents, the no-install form is npx -y @floomhq/floom@3.0.2 <command>.

Sign in

Your account starts on the web and the CLI connects with a browser device flow.

From the web

Go to floom.dev/login and continue with Google or email. You land in your workspace Library at /library. If it is brand new, the page says Your library is empty.

From the CLI

$ floom login

The CLI opens the browser device flow and prints a short code. Approve the request in the browser and the CLI stores the session at ~/.floom/auth.json.

Check who you are signed in as:

$ floom account

Push a skill

Push your first skill. This matches the empty Library path: Push your first skill.

$ floom push ~/.claude/skills/my-skill

The folder must contain a SKILL.md file. Floom uploads that folder into your Library and records it as a skill version.

Floom can also scan your agent skill folders automatically. Run floom push from anywhere to compare each local skill with your Library.

$ floom push

Don't have a skill folder yet? Create a ready-to-edit one:

$ floom new my-skill --agent claude

Each push creates a new version. Re-running push on an updated folder publishes a new version automatically. Use --dry-run to preview the plan, or --json for a machine-readable plan.

Removing a skill

From the CLI:

$ floom delete <slug>

The CLI asks you to type the skill name to confirm. Local copies in your agents are not deleted. Pass --yes for scripted use.

From the web: open the skill page at /library/<slug> and use the Delete this skill action in the Danger card.

Push from any editor (Codex, Cursor, plain shell)

Floom doesn't care which editor you use. A skill is just a folder with a SKILL.md file at its root — write it with any editor, then publish it with one CLI call.

1. Write the skill anywhere

mkdir my-skill
$EDITOR my-skill/SKILL.md

SKILL.md is plain Markdown with a small YAML frontmatter block on top: name, description, and an optional metadata section. Add any reference files (examples, snippets) next to it in the same folder.

---
name: my-skill
description: A short, plain-language description of what this skill does.
---

# My skill

The body of SKILL.md is the prompt your agent loads when it invokes the skill.

2. Publish to the Library

$ floom push ./my-skill

The first push creates the skill in your Library at version v1. Re-pushing the same folder publishes a new version automatically.

3. Use it from your editor of choice

Pull the Library into whichever agent you actually use:

$ floom pull --target codex      # writes to ~/.codex/skills/
$ floom pull --target cursor     # writes to ~/.cursor/skills/
$ floom pull --target gemini     # writes to ~/.gemini/skills/
$ floom pull --target opencode   # writes to ~/.opencode/skills/
$ floom pull --all-agents        # write to every detected agent

Floom resolves the right install path per agent — no manual copying. The shared content is identical; only the on-disk location differs.

Tip — install once, drop the npx prefix

If you're using npx -y @floomhq/floom every time, install globally so the floom binary lands on your PATH:

$ npm i -g @floomhq/floom

After that, every example on this page that uses npx -y @floomhq/floom ... works as plain floom ....

Pull into your agent

After the first push, run one sync command. Floom reviews both directions and syncs the Library into every detected AI agent on your machine.

$ floom sync

Use pull when you only want Library-to-local updates:

$ floom pull $ floom pull --agent claude $ floom pull --agent claude,codex

Zero-arg floom pull detects every AI agent on the machine and shows a per-agent plan. Pass --agent to limit it to one or more agents. Each command writes the full workspace library into that agent's skills directory, for example ~/.claude/skills/.

Skills can also be installed individually from a share link: floom install <share-url>

What was synced?

$ floom status

Invite teammates

Open /settings, type the teammate's email, click Invite. The invite link is emailed to them and also shown to you (copy fallback).

They open the link, sign in with their Google account, click Join workspace. They land in the same library you do — and can push / pull immediately.

Cancel an invite: in /settings, find the pending invite under Members and click Cancel.

Remove a member: in /settings, find the member row and click Remove. They lose access to the workspace immediately.

The Floom MCP

Some agents (Cursor, Gemini, OpenCode) read skills as MCP tools instead of pulling them into a directory. Floom ships a local MCP server you connect to:

$ npx -y @floomhq/floom mcp

Wire it into your agent's MCP config (for Cursor, edit .cursor/mcp.json). The server exposes five tools: floom_status, floom_sync, floom_search_skills, floom_get_skill, and floom_send_feedback.

CLI reference

# Correct — always use the full form:
$ npx -y @floomhq/floom@3.0.2 pull
$ npx -y @floomhq/floom@3.0.2 pull --agent claude
$ npx -y @floomhq/floom@3.0.2 push

# Wrong — do NOT use bare floom (different unrelated package):
# $ floom pull

The commands below match @floomhq/floom@3.0.2. Each command includes its canonical help summary, one runnable example, and the output shape to expect. Commands named init, ls, and search are not exposed by 3.0.2; use new and list instead.

Top-level help

$ npx -y @floomhq/floom@3.0.2 --help

Usage: floom [command]

Sign in
  login            sign in to your Floom workspace
  logout           sign out on this machine
  account          show account details   whoami (alias)

Move skills
  push [path]      publish local skills to the Library
  pull [skill]     update local agents from the Library
  sync             review both directions and resolve differences
  new <name>       create a ready-to-edit skill

Recover
  restore <skill>  restore a local skill from a safety backup

Library
  list             list team skills and local install status   library (alias)
  delete <skill>   delete a skill from the Library   remove (alias)
  install <link>   install a skill from a share link   add (alias)

Settings
  rename-device    set a friendly name for this machine   rename-machine (alias)

Inspect
  status           inspect sync state across Library and agents
  diff <skill>     compare local copies with the Library
  doctor           diagnose auth, agents, manifests, and version

Advanced
  mcp              run the local MCP server (for agent configuration)

Sign in

$ npx -y @floomhq/floom@3.0.2 login --help
Usage: floom login [options]

sign in to your Floom workspace

$ npx -y @floomhq/floom@3.0.2 login
Expected output:
  Open the device login URL printed by the CLI.
  Enter the short code in the browser.
  The CLI stores the approved session at ~/.floom/auth.json.

Account

$ npx -y @floomhq/floom@3.0.2 account --help
Usage: floom account [options]

show account details

Options:
  --json      print account state as JSON

$ npx -y @floomhq/floom@3.0.2 account
Expected output when signed out:
  Not signed in to Floom.

  Next
    floom login

Logout

$ npx -y @floomhq/floom@3.0.2 logout --help
Usage: floom logout [options]

sign out on this machine

$ npx -y @floomhq/floom@3.0.2 logout
Expected output:
  ✓ Signed out of Floom on this machine.
  Your local skill files in ~/.claude/skills, ~/.codex/skills, etc. were not changed.

Push

$ npx -y @floomhq/floom@3.0.2 push --help
Usage: floom push [options] [path]

publish local skills to the Library

Options:
  --yes              proceed with all safe changes
  --json             print the plan or result as JSON
  --dry-run          print the plan without changing anything
  --exit-zero        with --dry-run, force exit 0 even if the plan is non-empty
  --no-secret-check  skip the pre-publish secret scan
  --concurrency <n>  bulk push concurrency, 1-16 (default: "6")

$ npx -y @floomhq/floom@3.0.2 push ~/.claude/skills/my-skill --dry-run
Expected output:
  A push plan for the selected skill folder.
  No Library data changes because --dry-run is set.

Pull

$ npx -y @floomhq/floom@3.0.2 pull --help
Usage: floom pull [options] [skill]

update local agents from the Library

Options:
  --agent <name>   limit to one or more agents (repeatable, comma-separated)
  --target <name>  alias for --agent
  --all-agents     use every detected agent
  --global         use the user-level agent skills folder
  --project        use this project's agent skills folder
  --all-scopes     use both global and project-local copies
  --yes            skip confirmation for safe mutations
  --json           print the plan or result as JSON
  --dry-run        print the plan without changing anything

$ npx -y @floomhq/floom@3.0.2 pull --agent claude --dry-run
Expected output:
  A pull plan for Claude Code.
  No local files change because --dry-run is set.

Sync

$ npx -y @floomhq/floom@3.0.2 sync --help
Usage: floom sync [options]

review both directions and resolve differences

Options:
  --agent <name>   limit to one or more agents (repeatable, comma-separated)
  --target <name>  alias for --agent
  --all-agents     use every detected agent
  --global         use the user-level agent skills folder
  --project        use this project's agent skills folder
  --all-scopes     use both global and project-local copies
  --yes            skip confirmation for safe mutations
  --json           print the plan or result as JSON
  --dry-run        print the plan without changing anything

$ npx -y @floomhq/floom@3.0.2 sync --dry-run
Expected output:
  A two-way sync plan across detected agents and scopes.
  No files or Library records change because --dry-run is set.

New

$ npx -y @floomhq/floom@3.0.2 new --help
Usage: floom new [options] <name>

create a ready-to-edit skill

Options:
  --agent <name>  create in this agent's skills folder
  --all-scopes    (rejected — new creates one skill in one location)
  --yes           skip confirmation when non-interactive
  --json          print the plan or result as JSON
  --dry-run       print the plan without creating anything

$ npx -y @floomhq/floom@3.0.2 new research-helper --agent claude --dry-run
Expected output:
  A create-skill plan for Claude Code.
  No folder is created because --dry-run is set.

Restore

$ npx -y @floomhq/floom@3.0.2 restore --help
Usage: floom restore [options] [skill]

restore a local skill from a safety backup

Options:
  --agent <name>        the agent whose copy to restore
  --backup <timestamp>  restore a specific backup snapshot
  --list                list all available backups
  --yes                 skip confirmation
  --json                print the plan or result as JSON
  --dry-run             print the plan without restoring anything

$ npx -y @floomhq/floom@3.0.2 restore my-skill --agent claude --list
Expected output:
  Available safety backups for that skill and agent, or a clear no-backups message.

List

$ npx -y @floomhq/floom@3.0.2 list --help
Usage: floom list [options]

list team skills and local install status

Options:
  --json      print the Library as JSON

$ npx -y @floomhq/floom@3.0.2 list
Expected output:
  Your workspace Library skills with local install status.
  If signed out, the CLI prints the sign-in next step.

Delete

$ npx -y @floomhq/floom@3.0.2 delete --help
Usage: floom delete [options] [skill]

delete a skill from the Library

Options:
  --yes        skip the type-the-name confirmation
  --json       print the plan or result as JSON
  --dry-run    print the plan without deleting anything
  --exit-zero  with --dry-run, force exit 0 even if the plan is non-empty

$ npx -y @floomhq/floom@3.0.2 delete my-skill --dry-run
Expected output:
  A delete plan for the Library skill.
  No Library record is deleted because --dry-run is set.

Install

$ npx -y @floomhq/floom@3.0.2 install --help
Usage: floom install [options] <link>

install a skill from a share link

Options:
  --agent <name>   install into one or more agents (repeatable, comma-separated)
  --target <name>  alias for --agent
  --all-agents     install into every detected agent
  --global         install into the user-level agent skills folder
  --project        install into this project's agent skills folder
  --all-scopes     install into both global and project-local copies
  --yes            skip confirmation for safe mutations
  --json           print the plan or result as JSON
  --dry-run        print the plan without installing anything

$ npx -y @floomhq/floom@3.0.2 install https://floom.dev/s/example --agent claude --dry-run
Expected output:
  An install plan for the shared skill.
  No local files change because --dry-run is set.

Rename Device

$ npx -y @floomhq/floom@3.0.2 rename-device --help
Usage: floom rename-device [options] <label>

set a friendly name for this machine

$ npx -y @floomhq/floom@3.0.2 rename-device "Federico MacBook"
Expected output:
  The CLI confirms the local machine label used in sync status.

Status

$ npx -y @floomhq/floom@3.0.2 status --help
Usage: floom status [options]

inspect sync state across Library and agents

Options:
  --agent <name>   limit to one or more agents (repeatable, comma-separated)
  --target <name>  alias for --agent
  --verbose        show every skill in every agent
  --json           print status as JSON

$ npx -y @floomhq/floom@3.0.2 status --json
Expected output when signed out:
  {
    "workspace": { "signedIn": false, "librarySkillCount": null },
    "complete": true,
    "agents": [],
    "skillsNeedingAttention": []
  }

Diff

$ npx -y @floomhq/floom@3.0.2 diff --help
Usage: floom diff [options] <skill>

compare local copies with the Library

Options:
  --agent <name>  limit to one agent
  --json          print the comparison as JSON

$ npx -y @floomhq/floom@3.0.2 diff my-skill --agent claude
Expected output:
  A file-level comparison between the Library version and the local Claude copy.

Doctor

$ npx -y @floomhq/floom@3.0.2 doctor --help
Usage: floom doctor [options]

diagnose auth, agents, manifests, and version

Options:
  --json      print diagnostics as JSON

$ npx -y @floomhq/floom@3.0.2 doctor --json
Expected output:
  A JSON diagnostics object covering auth, detected agents, skill manifests, and CLI version.

MCP

$ npx -y @floomhq/floom@3.0.2 mcp --help
Usage: floom mcp [options]

run the local MCP server (for agent configuration)

$ npx -y @floomhq/floom@3.0.2 mcp
Expected output:
  Starts the local stdio MCP server.
  Configure this command in an agent MCP config instead of running it in a normal terminal.

Supported agents