@cogineai/mafs-cli

The command-line interface for MAFS — A Unified Virtual File System for AI Agents, and the local entry point into CogineX.

This package ships two binaries:

| Binary | Purpose | | --------- | -------------------------------------------------------------------------------------------------------- | | coginex | User-facing client: log in to CogineX, mount Workspaces locally, and bidirectionally sync them. | | mafs | Standalone MAFS daemon controller: run a local daemon, create raw workspaces, execute commands over RPC. |

If you have a CogineX account and want your Workspaces on disk, install this and run coginex login. If you only want a local MAFS daemon for agent development, use mafs directly.

Install

npm install -g @cogineai/mafs-cli

Or run on demand without installing:

npx -p @cogineai/mafs-cli coginex install

Requires Node.js ≥ 20. macOS or Linux for FUSE-based mounts.

coginex — quick start

# 1. Install the CogineX bootstrap skill for AI agents.
coginex install

# 2. Pair this device with your CogineX account (device-code flow).
coginex login

# 3. List Workspaces you have access to on the control plane.
coginex workspace list

# 4. Mount one locally. The current directory must be empty.
mkdir ~/work/my-workspace && cd ~/work/my-workspace
coginex mount <workspace-id> .

# 5. Start bidirectional sync (file watcher + remote polling).
coginex sync <workspace-id>

# 6. Inspect state at any time.
coginex status
coginex devices

coginex commands

| Command | What it does | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | coginex install | Installs the bundled CogineX agent skill globally, then prints the next setup commands. | | coginex login | Pairs the current device via OAuth device-code flow; stores the long-term client token in the OS keychain. | | coginex logout | Best-effort tears down active mounts (sending unmount events), then revokes and clears the local token. | | coginex workspace list | Lists all Workspaces visible to this client, with mount status and access level. | | coginex workspace refresh <workspace-id> | Pulls remote-side changes for a single mount and writes them locally, skipping in-flight uploads. | | coginex workspace resolve <path> | Resolves a .conflict sibling left by sync by uploading the current local file as the resolved version. | | coginex mount <workspace-id> <path> | Initial pull from R2 → local empty directory; persists the mount in ~/.config/coginex/mounts.json. | | coginex sync <workspace-id> | Long-running bidirectional sync. Local writes are uploaded with If-Match; remote changes are polled. | | coginex status | Shows local mount state, sync engine status, and credential expiry. | | coginex devices | Shows the local client / device record (without leaking secrets). | | coginex info | Prints version + build metadata. |

Commands that expose state default to human-readable text. Use -o json or --output json for stable machine-readable output for scripts, CI, and agents; --json remains a compatibility alias where it already exists.

Run any command with --help for the full flag set, including --heartbeat-ms, --mock-server, output-format flags, and policy-override flags surfaced by individual subcommands.

CogineX agent skill

This package includes skills/coginex/SKILL.md, the global CogineX bootstrap skill for agents. It teaches agents to use the ordinary coginex CLI to check install, config, login, accessible Workspaces, local mounts, refresh/status, and Workspace entry before handing off to Workspace-local files and skills.

Install or refresh the skill explicitly:

coginex install

coginex install copies the bundled skill into the global Agent skills store via npx -y skills add ... --skill coginex -y -g --copy. It is intentionally a user-invoked setup command, not an npm postinstall side effect. Use coginex install --dry-run to inspect the exact command first.

The skill is not a separate agent command surface. Agents should still use coginex --help, command-specific help, and -o json / --output json for structured state.

mafs — standalone daemon

The mafs binary is the original Mirage CLI surface. It speaks to a @cogineai/mafs-server daemon over its HTTP API and gives you a CogineX-free environment for ad-hoc agent or workspace work.

# The daemon auto-spawns on the first command that needs it (default
# 127.0.0.1:8765). Use `mafs daemon status` to check, and `restart`,
# `stop`, or `kill` to manage lifecycle.
mafs daemon status

# Create a workspace from a YAML descriptor.
mafs workspace create ws.yaml --id demo

# Execute a shell command inside the workspace.
mafs execute --workspace demo --command "cp /s3/report.csv /data/report.csv"

# Snapshot for portability.
mafs workspace snapshot demo demo.tar

Top-level subcommands: workspace, session, job, execute, provision, daemon. Each subcommand exposes its own --help. The daemon subcommand only manages an existing daemon (status, stop, restart, kill); it has no start action because the daemon is auto-spawned on demand by other subcommands.

Configuration

coginex reads from these environment variables and config files:

• COGINEX_API_URL — CogineX control-plane base URL. Overrides config files and defaults.
• XDG_CONFIG_HOME — when set, config and mount state live under $XDG_CONFIG_HOME/coginex/.
• COGINEX_MOUNT_STATE — optional override for the local mount registry path.
• MAFS_DAEMON_PORT — Port the auto-spawned mafs-daemon listens on (default 8765). The daemon always binds to 127.0.0.1.
• MAFS_ALLOWED_HOSTS — daemon Host-header allow-list (DNS-rebinding protection; see @cogineai/mafs-server).

coginex also reads api_base_url from ~/.config/coginex/config.toml or from a [coginex] table in that file.

Persistent CogineX state lives under ~/.config/coginex/ by default:

• mounts.json — local mount registry (one entry per coginex mount).

The long-term CogineX Client Token is stored in macOS Keychain in the current V1 implementation. Short-lived R2 credentials are held in memory by the sync or refresh command that requested them.

Programmatic API

This package is published primarily as a CLI; importing from @cogineai/mafs-cli is intended only for adjacent CogineX tooling. Library consumers should depend on @cogineai/mafs-node (Node runtime) or @cogineai/mafs-core (runtime-agnostic) instead.

Companion packages

• @cogineai/mafs-core — runtime-agnostic Workspace, Resource, ops registry.
• @cogineai/mafs-node — Node-side resources (S3, R2, GCS, GitHub, …) and FUSE.
• @cogineai/mafs-browser — browser/edge bundle (RAM, OPFS, S3 via presigned URLs).
• @cogineai/mafs-server — mafs-daemon HTTP server.
• @cogineai/mafs-agents — adapters for OpenAI / Vercel / LangChain / Mastra / pi.

License & attribution

Apache-2.0. MAFS is a fork of Mirage; see the project-level NOTICE for attribution and the relationship to upstream.