CLI service and files

The onemind CLI Service And Files page covers the background service, Mind library, update procedure, and local state for each installed component.

Background Service

The installer registers a per-user service:

• macOS: LaunchAgent at ~/Library/LaunchAgents/com.onemind.cli.daemon.plist
• Linux: systemd user service at ~/.config/systemd/user/onemind.service

Check it with:

onemind service status

Restart it with:

onemind service stop
onemind service start

Recreate its definition after moving the binary or repairing an installation:

onemind service install

On macOS, daemon output is written to ~/Library/Logs/OneMind/daemon.log (standard output) and ~/Library/Logs/OneMind/daemon-error.log (error output).

Mind Library

The Mind library is Project-scoped private file space under the team's shared storage quota. By default, every onemind files operation resolves the most specific active ordinary Project binding that contains the current working directory. It fails closed instead of silently falling back to the Team Project. Add --team only when the Team Project is intentional. The same files are available in the onemind BETA app's Mind Library page.

Use onemind files to list the whole library and its quota summary. Add --prefix to inspect one directory-like path, or --json for machine-readable output:

onemind files
onemind files list --prefix skills/writing
onemind files list --prefix assets --json
onemind files list --team

For the minimal per-task freshness check used by managed AI instructions, run:

onemind files check --quiet --wait --ai codex

The background service normally checks assigned files on launch, relevant server events, authentication or network reconnect, and a backoff-aware 15-minute fallback. It creates or reuses approval requests without involving the AI. Managed instructions name the assigned relative paths and always provide the exact caller with --ai, which is required to disambiguate multi-tool Project directories. The command discovers only files whose projectIDs and aiTargets assignments match that exact binding. It hashes local regular files, rejects symlinks and special files, and sends only metadata to the server. A current wait is completely silent. Approval prints only Updated <path>.; Refuse emits project_file_refused, exits 3, blocks work that depends on the refused file, and must not be retried automatically. Exhausting the request-derived network/server retry deadline emits project_file_wait_exhausted, exits 4, and likewise forbids automatic retry. Defer also exits nonzero while the durable request remains pending. After exit 0, the caller must read the refreshed local file before relying on it.

Governed check target keys: codex, cursor, qoder, claude_code, antigravity, openclaw, opencode, hermes, pi, grok_build, deepseek_harness, trae, workbuddy. Mind-assignment upload target keys: codex, cursor, qoder, claude_code, antigravity, openclaw, opencode, hermes, pi, grok_build, deepseek_harness, trae, workbuddy.

A stale file creates or reuses one device-scoped request. Approve, Refuse, Defer, or Cancel in the onemind BETA app's Project file updates page. Public states remain pending, refused, approved_awaiting_apply, applied, expired, conflict, and failed; Defer leaves the state pending. Status waits use authenticated bounded long-polls with reconnect backoff, not frequent polling. After one-time approval the single-writer executor revalidates both hashes and the selected Project head, verifies downloaded content, preserves an exact recovery copy in onemind-owned application state outside the checkout, replaces through a flushed sibling temporary file, and acknowledges the result. Any local, remote, binding, symlink, special-file, or expiry change fails closed. Closing the waiting command never cancels the request, so the service can still apply a later approval.

Applied identities are recorded in a versioned checkpoint manifest under the operating system's onemind application-state directory. Local request/replacement evidence and recovery copies live beside it, never in the Project checkout. An in-flight apply persists its device-bound attempt ID, acknowledgement idempotency key, negotiated protocol, stage, and rotating short lease in the mode-0600 manifest so a crash can reclaim or resume the same one-time authorization. Legacy server grants are durably resumed without a second claim. Terminal checkpoints remove secrets; recovery storage is capped at 100 MiB and unprotected copies expire after seven days.

Mind paths are relative, slash-separated paths. Every upload requires --ai so the proposal explicitly identifies which AI targets may use the file. Use the Mind-assignment upload target keys above and a comma-separated value such as --ai codex,cursor for multiple targets. Submitting a single file without --to uses its local file name. For example, this proposes release-review.md for ChatGPT (codex) and Cursor:

onemind files upload --ai codex ./release-review.md

Use --to to choose an explicit Mind path. Prompt files are conventionally kept below prompts/:

onemind files upload --ai codex,cursor --to prompts/release-review.md ./release-review.md

Directories are uploaded recursively. --to is the Mind destination root, and every descendant keeps its relative path. Given this local skill directory:

writing/
├── SKILL.md
├── examples/
│   └── example.json
└── references/
    └── style.md

upload it with:

onemind files upload --ai codex,claude_code --to skills/writing ./writing

The pending review queue receives proposals for skills/writing/SKILL.md, skills/writing/examples/example.json, and skills/writing/references/style.md. A directory upload stops before submitting anything when its preflight finds an unsupported format.

Without --to, a directory uses its local directory name as the Mind root. The server compares every submitted file with approved Mind main: a missing path is labeled New file, a changed existing path is labeled New version, and identical content is reported as unchanged without creating a proposal. New-file and new-version proposals remain pending until an admin explicitly approves or rejects them on the selected Project's Mind Library page.

Multi-file submissions run sequentially. If a later file fails, earlier proposals remain pending, but approved Mind main is not changed. Resolve the reported error, inspect the pending queue in the Library page, and rerun the command. An exact retry reuses the identical pending proposal instead of creating another one. Approval appends an immutable Mind commit, preserves older versions in Project history, and then updates quota usage.

Download addresses one exact Mind file. Without --output, the CLI writes the Mind file's base name in the current directory. It refuses to overwrite an existing local file unless --force is present:

onemind files download skills/writing/SKILL.md
onemind files download --output ./writing-SKILL.md skills/writing/SKILL.md
onemind files download --force --output ./writing-SKILL.md skills/writing/SKILL.md

Deletion always requires --yes. Without --recursive, the path must match one exact file. With --recursive, deletion includes the exact path and descendants after a / path-segment boundary; a similarly named sibling prefix is not selected:

onemind files delete --yes prompts/release-review.md
onemind files delete --recursive --yes skills/writing

Recursive deletion also runs sequentially and is not atomic. If a later deletion fails, files deleted earlier in the operation remain deleted. Inspect the remaining prefix, resolve the error, and rerun the same confirmed command to finish cleanup.

Library files are inert storage. Uploading a prompt file does not change the active Project Mind, publish team memory, or bypass proposal and administrator-review governance. Uploading a skill, script, hook, or asset does not install or execute it on any device. onemind sync never mutates skills. Use onemind skills status, and use read-only onemind skills resolve NAME to obtain an exact verified SKILL.md path for a current skill without claiming the host refreshed its task-start registry. Explicitly choose exact names with install, update, or uninstall. onemind verifies downloads, protects local changes and Project boundaries, quarantines recoverable files, and records each completed or blocked action.

Update onemind

Run onemind update --check for a read-only release check. The Check for updates palette action runs the same read-only check. Bare onemind update shows the official signed-installer instructions, makes no changes, and exits with action-required status 3 so automation cannot report an update as completed. Neither path stops or starts the service, downloads an artifact, replaces the CLI binary, or changes local state.

The background service also checks for a new release on startup and every six hours, then prints a one-line notice to stderr and, on macOS and Linux, delivers a desktop notification when a newer version is found. The notice is not repeated for the same version.

To install a release, rerun the official installation command for your operating system from CLI quick start. The public macOS/Linux update command is CLI-only and uses ONEMIND_INSTALL_APP=0; on macOS it does not download, replace, configure, or open either OneMind.app or OneMind BETA.app. The official installer updates the CLI, signed AI-tool integration bundle, and installation binding together; it does not change AI-host plugins. Do not replace the CLI binary by itself, because that can leave integration state in repair_required until the complete signed release is installed. Afterward, run passive onemind integrations list --json and explicitly install, update, or repair only the targets that report those actions are needed.

Files And Local State

All active tool bindings for the same Project and root share this queue. The daemon's deterministic binding selection is only an upload-authorization route. A schema-v11 LearningEvent has no producer-tool identity. Proposal responses omit producer-tool identity entirely; that absence means the producer is not attributable, not that the selected uploader produced it. The retained device and account identify the authorized submission route and submitter, not the producing process.

Do not hand-edit the managed markers. Missing, duplicated, reversed, or malformed markers cause sync to stop instead of risking user-owned content.