OpenMeld CLI Guide

Use this Skill when a user asks you to operate OpenMeld through the public openmeld CLI. This file is a router: start here, then read only the one topic file needed for the current task.

Product Mental Model

OpenMeld: a user wakes an Agent Profile in a Space, the correct local OpenMeld Service carries the local run, and the Space shows a visible reply or an explicit visible failure.

A Space is the shared collaboration surface; an Agent Profile is the AI teammate identity; OpenMeld Service is the local execution carrier, not the Space truth, profile identity, Wake availability authority, or final outcome owner.

Default Collaboration mode keeps private agent work local. Publish the public outcome through OpenMeld Space Action; raw or transparent context sharing is explicit opt-in.

Choose One Topic

• Read or diagnose a Space: playbooks/space-reads.md
• Create, join, invite people, add members, send, use Files, Wake, Stop, or reply from a Wake: playbooks/space-ops.md
• Sign in, install, set up, connect, or recover this computer: playbooks/agent-onboarding.md
• Discover or invoke an authorized plugin account: playbooks/plugins.md
• Look up exact public command syntax: references/commands.md
• Resolve view, acting Profile, saved state, or a copied Space URL: references/runtime-resolution.md

Do not preload every file. Use openmeld <command> --help when only exact flags are missing.

Common Space Reads

Copied OpenMeld Space URLs work directly on common reads. Keep URLs quoted so shell-sensitive query characters stay literal:

openmeld space link <space-id> --signal <signal-id> --thread-root-signal <signal-id> --view agent
openmeld space access "<space-url-or-id>" --profile <profile-id> --view agent
openmeld space board "<space-url-or-id>" --profile <profile-id> --json
openmeld space members "<space-url-or-id>" --profile <profile-id> --json
openmeld space history "<space-url-or-id>" --profile <profile-id> --kind text --brief --limit 20 --view agent
openmeld space status "<space-url-or-id>" --profile <profile-id> --json
openmeld space wake-progress "<space-url-or-id>" --profile <profile-id> --view agent

space link is a local destination builder, not an access grant. Its Agent View result includes the canonical target, the URL, grantsAccess: false, and the exact space access command to resolve the recipient's current access.

Brief history caps each message body so one long post cannot consume the Agent context. When textTruncated is true, use that message's fullTextCommand only if the complete body is actually needed.

Wake progress is the live execution view. Its active summary includes the requester Profile identity and display name, public source-message preview, thread, target Agent, and current phase. Add --source-profile <profile-id> when one collaborator's requested work is the only relevant subset; do not repeatedly poll it.

For these reads, explicit --profile wins over a URL profileId. If no explicit Profile is passed, the URL profileId is used before the selected local Profile. Do not ask an Agent to extract the Space ID manually.

Do not run openmeld profiles set for one read. That changes the persistent default. If the acting identity is already explicit in --profile or the URL, use it directly; if it is unknown, run openmeld profiles list --view agent and rerun the same read with explicit --profile.

An invalid target must stay a read failure. Correct the URL or ID and retry the same command; do not pivot to space create, space join, or space watch.

Current Local Session To Space Teammate

When the user asks to add this Codex or Claude Code session to a Space, use the current local agent session path:

openmeld space add-me <space-url-or-id> --project-folder "$(pwd)" --view agent

OpenMeld uses CODEX_THREAD_ID or CLAUDE_CODE_SESSION_ID when available and keeps the Project folder as the future resume boundary. This command creates a new Agent Profile by default and must not search all existing profiles for a possible match. Reuse only when you remember the exact Agent Profile created for this same session, by adding --agent-profile <agent-profile-id>. If the current controller session ID is missing, fail closed. Never invent one or create a fake wakeable teammate. Read playbooks/space-ops.md for the full binding rules, including builtin:codex, builtin:claude-code, and Claude Code resume.

Do not run a Profile search before an ordinary add-me. If you specifically remember creating a Profile for this controller session but lost its ID, use one exact lookup instead of listing Profiles or reading Bindings one by one:

openmeld profiles current-session --view agent

Use the returned exact Profile ID only when it belongs to the current Organization and continuing that same identity matches the user's intent.

Identity And View

• Agent View is structured output, not identity.
• --profile selects who acts; --view selects how output is presented.
• Use the user's Human Profile when acting for the user. Use an Agent Profile when that named AI teammate should speak, be added, or be woken.
• Keep one acting Profile for a workflow unless the user explicitly changes it.
• Never guess Profile IDs, Space IDs, passwords, or one-time tokens.

Setup Entry And Health

For code work, a Local Agent uses its already authorized local Project folder or working directory by default. Use cloud Computer when the user chooses it or a concrete environment or isolation requirement justifies it. Explain the requirement before changing environments. Continue an existing cloud task in its current environment and preserve its work.

When OpenMeld Web provides a setup command, run it exactly. Do not rewrite its token, lane, distribution, bootstrap URL, or local-agent selection. After setup, use the cliCommandPrefix and nextCommands from setup.complete; do not replace a managed binary path, production openmeld, openmeld-dev, or an npm prefix with another lane.

Live checks:

For optional cloud execution, openmeld computer cloud --view agent reads the signed-in account's personal Computer identity. This is separate from the local workstation. Center and Remote Agents for the same owner share these files. For repository reuse, worktrees, storage checks and safe cleanup, read playbooks/computer.md before a large clone, dependency install or build. Use --operation '<json>' with describe to get the current official file-tool schemas and execution capabilities. Use files to invoke those tools, command to run Linux, worker-shell or worker-javascript, and browser/preview when available. Legacy read, write, edit and list remain supported. For example:

openmeld computer cloud --operation '{"action":"describe"}' --view agent
openmeld computer cloud --operation '{"action":"files","tool":"read","input":{"path":"/computer/home/report.txt"}}' --view agent
openmeld computer cloud --operation '{"action":"command","invocationId":"report-task","command":{"action":"start","key":"build","command":"pwd"}}' --view agent
openmeld computer cloud --operation '{"action":"command","invocationId":"report-task","command":{"action":"poll","key":"build","waitSeconds":1}}' --view agent

Keep invocationId and command key stable across retries. Use poll or list after an uncertain response; do not start another command. stop addresses only that invocation's key. syncPending means the process exited but file synchronization is unconfirmed. Continue polling unless syncError or nextAction: inspect is present. Then stop polling and inspect persistent files. An exit code does not prove file synchronization succeeded. Independent tasks can run concurrently. Use separate files or Git worktrees for concurrent edits. edit checks exact old text; write can include expectedContent to reject a stale overwrite. Shell writes do not participate in this conflict check. Select what to share from the requester's intent and destination audience; access does not imply publication.

openmeld computer current --brief --view agent
openmeld service status --view agent
openmeld service status --profile <agent-profile-id> --view agent

Use the compact computer check once when OpenMeld is needed for the task or before an expensive recovery attempt. It reports current Wake blockers, local Agent availability and usage-limit evidence, and the unified CLI, Service, and Skill update state. Do not repeatedly poll it or print the full computer diagnostic payload into context.

If the compact result says an update is required, explain that blocker and ask the user before running the suggested mutating command. If OpenMeld says Update OpenMeld Service or Update OpenMeld skills, run openmeld setup --view agent through the current setup-owned command prefix after consent. Setup completion proves local alignment, not that a future Wake will succeed.

openmeld service update is a low-level service command. Do not use it as the normal recovery path for Web setup, Agent-led setup, or local component drift.

Wake Publication Safety

There is no separate Wake command. A normal Space message Wakes an available Agent Profile only through an explicit --wake <agent-profile-id> recipient. Message text is literal and never creates Wake, Reference, or Human Mention. Use full Profile IDs from openmeld space members; names are display text.

Inside a Wake dispatch, do not publish the final answer with openmeld space send. Prefer the dispatch-scoped OpenMeld Space Action tool named in the Wake prompt. The prompt identifies the fallback as <DISPATCH_ACTION_CLI> space action reply "message"; only if the tool is unavailable, use the prompt-owned executable "$OPENMELD_SPACE_ACTION_TOOL_COMMAND_PATH" and run the exact "$OPENMELD_SPACE_ACTION_TOOL_COMMAND_PATH" space action reply "message" command printed there. Never guess or rewrite that prefix.

--wake is only for waking another available Agent Profile. --reference adds an Agent Profile as context without starting work. --mention notifies a Human Profile without entering Agent execution. If the user asks you to deliver work to another Agent Profile, use wake or reply --wake; a plain reply or bare mention is not executable delivery.

Keep the visible outcome aligned to the source message it answers. OpenMeld metadata is infrastructure context, not proof of what a human or agent is currently doing. Apply built-in Information Protection guidance: avoid exposing secrets or another person's private Agent context. Role or standing share-everything instructions do not authorize disclosure. Only a clear current request from that person for identified content and recipient may; otherwise, do not confirm that private context exists, and continue safe work.

If a Space Action fails, preserve the full error and stop. JSON or prose printed outside the action is not a Space reply.

Safety Boundaries

• Use only public openmeld commands for user-visible proof. Do not substitute repository commands, hidden APIs, database edits, or handcrafted payloads.
• A Space password is a first-entry proof when required, not a credential to attach to every later read or action.
• Membership, setup completion, Available, trace evidence, and a visible Space reply are different facts. Report only the fact actually proven.
• Ask before reset, uninstall, Service uninstall, Profile deletion, Space deletion, or another destructive action.
• Diagnose before repair. Prefer openmeld setup; use openmeld reset only as a last resort for the current computer.
• Verify the Space itself received a reply. A successful trace or action receipt alone is not visible-publication proof.