{"_id":"@cogineai/mafs-cli","_rev":"8-19f74d88a93fc5cd1467b982946dd9d1","name":"@cogineai/mafs-cli","dist-tags":{"alpha":"0.1.0-alpha.3","latest":"0.1.0-alpha.3"},"versions":{"0.1.0-alpha.0":{"name":"@cogineai/mafs-cli","version":"0.1.0-alpha.0","keywords":["bash","fuse","typescript","vfs","ai-agents","agent-sandbox","langchain","virtual-filesystem","llm-agents","agent-tools","claude-code","openai-agents"],"author":{"name":"lc708","email":"kiedis@foxmail.com"},"license":"Apache-2.0","_id":"@cogineai/mafs-cli@0.1.0-alpha.0","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"homepage":"https://github.com/cogine-ai/CogineX-mono#readme","bugs":{"url":"https://github.com/cogine-ai/CogineX-mono/issues"},"bin":{"mafs":"dist/bin/mafs.js","coginex":"dist/bin/coginex.js"},"dist":{"shasum":"7ff46a07a27e9904a614eabdfad34f48e6b85456","tarball":"https://registry.npmjs.org/@cogineai/mafs-cli/-/mafs-cli-0.1.0-alpha.0.tgz","fileCount":13,"integrity":"sha512-Nn6BtIgLeLtFBD1PmcCUWMAt2bjgpGxc7wPdXbOsHU3NZNUUDSsVkYwGAbit4KVZek3TfRdMA/KwbstXC+EgiQ==","signatures":[{"sig":"MEUCIA7Q6pjn/HXn/YG0Is1I8Y5SQg9gCFGI0FQwI+78+pLDAiEA921okdi7mLkzppWDL2m6g5U2egyA5YFF4isOO/nPsTw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":607561},"main":"./dist/index.js","type":"module","_from":"file:cogineai-mafs-cli-0.1.0-alpha.0.tgz","types":"./dist/index.d.ts","scripts":{"test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"_resolved":"/private/var/folders/w3/1jnv2n65319gjrn7xmghv87m0000gn/T/3b055295f6e3cd2ed6ca443945db0a46/cogineai-mafs-cli-0.1.0-alpha.0.tgz","_integrity":"sha512-Nn6BtIgLeLtFBD1PmcCUWMAt2bjgpGxc7wPdXbOsHU3NZNUUDSsVkYwGAbit4KVZek3TfRdMA/KwbstXC+EgiQ==","repository":{"url":"git+https://github.com/cogine-ai/CogineX-mono.git","type":"git","directory":"packages/mafs/typescript/packages/cli"},"_npmVersion":"10.9.2","description":"mafs CLI for agent workspace filesystems","directories":{},"_nodeVersion":"22.16.0","dependencies":{"yaml":"^2.6.0","commander":"^14.0.0","smol-toml":"^1.3.0","@aws-sdk/client-s3":"^3.1033.0","@cogineai/mafs-server":"0.1.0-alpha.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^3.0.0","typescript":"^6.0.0","@types/node":"^22.0.0","aws-sdk-client-mock":"^4.1.0"},"_npmOperationalInternal":{"tmp":"tmp/mafs-cli_0.1.0-alpha.0_1779464762421_0.30266778733139343","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.1":{"name":"@cogineai/mafs-cli","version":"0.1.0-alpha.1","keywords":["bash","fuse","typescript","vfs","ai-agents","agent-sandbox","langchain","virtual-filesystem","llm-agents","agent-tools","claude-code","openai-agents"],"author":{"name":"lc708","email":"kiedis@foxmail.com"},"license":"Apache-2.0","_id":"@cogineai/mafs-cli@0.1.0-alpha.1","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"homepage":"https://github.com/cogine-ai/CogineX-mono#readme","bugs":{"url":"https://github.com/cogine-ai/CogineX-mono/issues"},"bin":{"mafs":"dist/bin/mafs.js","coginex":"dist/bin/coginex.js"},"dist":{"shasum":"bc4c00402972482b104dd55e38e406513ef359d9","tarball":"https://registry.npmjs.org/@cogineai/mafs-cli/-/mafs-cli-0.1.0-alpha.1.tgz","fileCount":13,"integrity":"sha512-snBptrCSqI4fmYbeBtn44vreFoLmLB65Q3y9oX4qaO+gi1Rb9asEciNMw6td3Y9+bDhYcbDzMTcb+1RsY7MfNw==","signatures":[{"sig":"MEUCIBINOmTjgKF4ET7sAC0NJS6PBWBu1K9neH0JiQ/38NRrAiEAyONHjkYAcdwLabxbTy88jiqF58WXV3TJzXy7og5IQoI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":613409},"main":"./dist/index.js","type":"module","_from":"file:cogineai-mafs-cli-0.1.0-alpha.1.tgz","types":"./dist/index.d.ts","scripts":{"test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"_resolved":"/private/var/folders/w3/1jnv2n65319gjrn7xmghv87m0000gn/T/43d8a6c7ed3278b9ab60115ec405dfd8/cogineai-mafs-cli-0.1.0-alpha.1.tgz","_integrity":"sha512-snBptrCSqI4fmYbeBtn44vreFoLmLB65Q3y9oX4qaO+gi1Rb9asEciNMw6td3Y9+bDhYcbDzMTcb+1RsY7MfNw==","repository":{"url":"git+https://github.com/cogine-ai/CogineX-mono.git","type":"git","directory":"packages/mafs/typescript/packages/cli"},"_npmVersion":"10.9.2","description":"mafs CLI for agent workspace filesystems","directories":{},"_nodeVersion":"22.16.0","dependencies":{"yaml":"^2.6.0","commander":"^14.0.0","smol-toml":"^1.3.0","@aws-sdk/client-s3":"^3.1033.0","@cogineai/mafs-server":"0.1.0-alpha.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"tsup":"^8.5.0","vitest":"^3.0.0","typescript":"^6.0.0","@types/node":"^22.0.0","aws-sdk-client-mock":"^4.1.0"},"_npmOperationalInternal":{"tmp":"tmp/mafs-cli_0.1.0-alpha.1_1779796359322_0.4718315505278472","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.2":{"name":"@cogineai/mafs-cli","version":"0.1.0-alpha.2","keywords":["bash","fuse","typescript","vfs","ai-agents","agent-sandbox","langchain","virtual-filesystem","llm-agents","agent-tools","claude-code","openai-agents"],"author":{"name":"lc708","email":"kiedis@foxmail.com"},"license":"Apache-2.0","_id":"@cogineai/mafs-cli@0.1.0-alpha.2","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"homepage":"https://github.com/cogine-ai/CogineX-mono#readme","bugs":{"url":"https://github.com/cogine-ai/CogineX-mono/issues"},"bin":{"mafs":"dist/bin/mafs.js","coginex":"dist/bin/coginex.js"},"dist":{"shasum":"993f81a31cc5daa491f83cfc6e528b0ed03854f5","tarball":"https://registry.npmjs.org/@cogineai/mafs-cli/-/mafs-cli-0.1.0-alpha.2.tgz","fileCount":15,"integrity":"sha512-ro85L4pRQM40q5lEYSZSBxSIuvi9LdvC0gvH49NAxIwHlXfr0retle/ic/MJ+EtRE/3b98AybRz+vxPnYw8rTg==","signatures":[{"sig":"MEUCIAQE5LNV4Mq3dxOvXNualIDTbMcjhQHRVI1YoB/pZnhAAiEArIxdYnErLwXb4tuhYhY8+PWT4zoCsA1Ihu1EI44XRJQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":639306},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","scripts":{"test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"repository":{"url":"git+https://github.com/cogine-ai/CogineX-mono.git","type":"git","directory":"packages/mafs/typescript/packages/cli"},"_npmVersion":"10.9.2","description":"mafs CLI for agent workspace filesystems","directories":{},"_nodeVersion":"22.16.0","dependencies":{"yaml":"^2.6.0","commander":"^14.0.0","smol-toml":"^1.3.0","@aws-sdk/client-s3":"^3.1033.0","@cogineai/mafs-server":"workspace:*"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^3.0.0","typescript":"^6.0.0","@types/node":"^22.0.0","aws-sdk-client-mock":"^4.1.0"},"_npmOperationalInternal":{"tmp":"tmp/mafs-cli_0.1.0-alpha.2_1780007240246_0.8933200567445787","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Broken release: contains workspace:* dependency; use 0.1.0-alpha.3."},"0.1.0-alpha.3":{"name":"@cogineai/mafs-cli","version":"0.1.0-alpha.3","keywords":["bash","fuse","typescript","vfs","ai-agents","agent-sandbox","langchain","virtual-filesystem","llm-agents","agent-tools","claude-code","openai-agents"],"author":{"name":"lc708","email":"kiedis@foxmail.com"},"license":"Apache-2.0","_id":"@cogineai/mafs-cli@0.1.0-alpha.3","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"homepage":"https://github.com/cogine-ai/CogineX-mono#readme","bugs":{"url":"https://github.com/cogine-ai/CogineX-mono/issues"},"bin":{"mafs":"dist/bin/mafs.js","coginex":"dist/bin/coginex.js"},"dist":{"shasum":"134030c516f3195cd1234617e2c57d32d864e240","tarball":"https://registry.npmjs.org/@cogineai/mafs-cli/-/mafs-cli-0.1.0-alpha.3.tgz","fileCount":15,"integrity":"sha512-4GMR4aRrnf58G1Qk1v84NYc8FZgNoVXgk2oT9fMjVhKInnIIrA8dsZf+n2oJTimpOJlvAgIqClPAgbIvbogNWw==","signatures":[{"sig":"MEQCIB24sjwAtjl+B/f5hpUHfkUL6yEQfKBTTR2Tar2n9TpbAiAOX0I1TULOmQClMRBtDNYfp1ExG7pog4N0hq+sI+/XBQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":639312},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","scripts":{"test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"repository":{"url":"git+https://github.com/cogine-ai/CogineX-mono.git","type":"git","directory":"packages/mafs/typescript/packages/cli"},"_npmVersion":"10.9.2","description":"mafs CLI for agent workspace filesystems","directories":{},"_nodeVersion":"22.16.0","dependencies":{"yaml":"^2.6.0","commander":"^14.0.0","smol-toml":"^1.3.0","@aws-sdk/client-s3":"^3.1033.0","@cogineai/mafs-server":"0.1.0-alpha.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^3.0.0","typescript":"^6.0.0","@types/node":"^22.0.0","aws-sdk-client-mock":"^4.1.0"},"_npmOperationalInternal":{"tmp":"tmp/mafs-cli_0.1.0-alpha.3_1780007650686_0.4424487180911816","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-22T15:46:02.305Z","modified":"2026-05-28T22:36:28.228Z","0.1.0-alpha.0":"2026-05-22T15:46:02.569Z","0.1.0-alpha.1":"2026-05-26T11:52:39.490Z","0.1.0-alpha.2":"2026-05-28T22:27:20.476Z","0.1.0-alpha.3":"2026-05-28T22:34:10.854Z"},"bugs":{"url":"https://github.com/cogine-ai/CogineX-mono/issues"},"author":{"name":"lc708","email":"kiedis@foxmail.com"},"license":"Apache-2.0","homepage":"https://github.com/cogine-ai/CogineX-mono#readme","keywords":["bash","fuse","typescript","vfs","ai-agents","agent-sandbox","langchain","virtual-filesystem","llm-agents","agent-tools","claude-code","openai-agents"],"repository":{"url":"git+https://github.com/cogine-ai/CogineX-mono.git","type":"git","directory":"packages/mafs/typescript/packages/cli"},"description":"mafs CLI for agent workspace filesystems","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"readme":"# @cogineai/mafs-cli\n\n[![npm version](https://img.shields.io/npm/v/%40cogineai%2Fmafs-cli.svg)](https://www.npmjs.com/package/@cogineai/mafs-cli)\n[![License](https://img.shields.io/npm/l/%40cogineai%2Fmafs-cli.svg)](https://github.com/cogine-ai/CogineX-mono/blob/main/packages/mafs/LICENSE)\n\nThe command-line interface for **MAFS — A Unified Virtual File System for AI Agents**, and the local entry point into [CogineX](https://github.com/cogine-ai/CogineX-mono).\n\nThis package ships two binaries:\n\n| Binary    | Purpose                                                                                                  |\n| --------- | -------------------------------------------------------------------------------------------------------- |\n| `coginex` | User-facing client: log in to CogineX, mount Workspaces locally, and bidirectionally sync them.          |\n| `mafs`    | Standalone MAFS daemon controller: run a local daemon, create raw workspaces, execute commands over RPC. |\n\nIf 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.\n\n## Install\n\n```bash\nnpm install -g @cogineai/mafs-cli\n```\n\nOr run on demand without installing:\n\n```bash\nnpx -p @cogineai/mafs-cli coginex install\n```\n\nRequires Node.js ≥ 20. macOS or Linux for FUSE-based mounts.\n\n## `coginex` — quick start\n\n```bash\n# 1. Install the CogineX bootstrap skill for AI agents.\ncoginex install\n\n# 2. Pair this device with your CogineX account (device-code flow).\ncoginex login\n\n# 3. List Workspaces you have access to on the control plane.\ncoginex workspace list\n\n# 4. Mount one locally. The current directory must be empty.\nmkdir ~/work/my-workspace && cd ~/work/my-workspace\ncoginex mount <workspace-id> .\n\n# 5. Start bidirectional sync (file watcher + remote polling).\ncoginex sync <workspace-id>\n\n# 6. Inspect state at any time.\ncoginex status\ncoginex devices\n```\n\n### `coginex` commands\n\n| Command                                          | What it does                                                                                               |\n| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |\n| `coginex install`                                | Installs the bundled CogineX agent skill globally, then prints the next setup commands.                    |\n| `coginex login`                                  | Pairs the current device via OAuth device-code flow; stores the long-term client token in the OS keychain. |\n| `coginex logout`                                 | Best-effort tears down active mounts (sending unmount events), then revokes and clears the local token.    |\n| `coginex workspace list`                         | Lists all Workspaces visible to this client, with mount status and access level.                           |\n| `coginex workspace refresh <workspace-id>`       | Pulls remote-side changes for a single mount and writes them locally, skipping in-flight uploads.          |\n| `coginex workspace resolve <path>`               | Resolves a `.conflict` sibling left by sync by uploading the current local file as the resolved version.   |\n| `coginex mount <workspace-id> <path>`            | Initial pull from R2 → local empty directory; persists the mount in `~/.config/coginex/mounts.json`.       |\n| `coginex sync <workspace-id>`                    | Long-running bidirectional sync. Local writes are uploaded with `If-Match`; remote changes are polled.     |\n| `coginex status`                                 | Shows local mount state, sync engine status, and credential expiry.                                        |\n| `coginex devices`                                | Shows the local client / device record (without leaking secrets).                                          |\n| `coginex info`                                   | Prints version + build metadata.                                                                           |\n\nCommands that expose state default to human-readable text. Use `-o json` or\n`--output json` for stable machine-readable output for scripts, CI, and agents;\n`--json` remains a compatibility alias where it already exists.\n\nRun 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.\n\n### CogineX agent skill\n\nThis package includes `skills/coginex/SKILL.md`, the global CogineX bootstrap\nskill for agents. It teaches agents to use the ordinary `coginex` CLI to check\ninstall, config, login, accessible Workspaces, local mounts, refresh/status, and\nWorkspace entry before handing off to Workspace-local files and skills.\n\nInstall or refresh the skill explicitly:\n\n```bash\ncoginex install\n```\n\n`coginex install` copies the bundled skill into the global Agent skills store\nvia `npx -y skills add ... --skill coginex -y -g --copy`. It is intentionally a\nuser-invoked setup command, not an npm `postinstall` side effect. Use\n`coginex install --dry-run` to inspect the exact command first.\n\nThe skill is not a separate agent command surface. Agents should still use\n`coginex --help`, command-specific help, and `-o json` / `--output json` for\nstructured state.\n\n## `mafs` — standalone daemon\n\nThe `mafs` binary is the original Mirage CLI surface. It speaks to a [`@cogineai/mafs-server`](../server) daemon over its HTTP API and gives you a CogineX-free environment for ad-hoc agent or workspace work.\n\n```bash\n# The daemon auto-spawns on the first command that needs it (default\n# 127.0.0.1:8765). Use `mafs daemon status` to check, and `restart`,\n# `stop`, or `kill` to manage lifecycle.\nmafs daemon status\n\n# Create a workspace from a YAML descriptor.\nmafs workspace create ws.yaml --id demo\n\n# Execute a shell command inside the workspace.\nmafs execute --workspace demo --command \"cp /s3/report.csv /data/report.csv\"\n\n# Snapshot for portability.\nmafs workspace snapshot demo demo.tar\n```\n\nTop-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.\n\n## Configuration\n\n`coginex` reads from these environment variables and config files:\n\n- `COGINEX_API_URL` — CogineX control-plane base URL. Overrides config files and defaults.\n- `XDG_CONFIG_HOME` — when set, config and mount state live under `$XDG_CONFIG_HOME/coginex/`.\n- `COGINEX_MOUNT_STATE` — optional override for the local mount registry path.\n- `MAFS_DAEMON_PORT` — Port the auto-spawned `mafs-daemon` listens on (default `8765`). The daemon always binds to `127.0.0.1`.\n- `MAFS_ALLOWED_HOSTS` — daemon Host-header allow-list (DNS-rebinding protection; see [`@cogineai/mafs-server`](../server)).\n\n`coginex` also reads `api_base_url` from `~/.config/coginex/config.toml` or from\na `[coginex]` table in that file.\n\nPersistent CogineX state lives under `~/.config/coginex/` by default:\n\n- `mounts.json` — local mount registry (one entry per `coginex mount`).\n\nThe long-term CogineX Client Token is stored in macOS Keychain in the current V1\nimplementation. Short-lived R2 credentials are held in memory by the sync or\nrefresh command that requested them.\n\n## Programmatic API\n\nThis 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) (Node runtime) or [`@cogineai/mafs-core`](../core) (runtime-agnostic) instead.\n\n## Companion packages\n\n- [`@cogineai/mafs-core`](../core) — runtime-agnostic Workspace, Resource, ops registry.\n- [`@cogineai/mafs-node`](../node) — Node-side resources (S3, R2, GCS, GitHub, …) and FUSE.\n- [`@cogineai/mafs-browser`](../browser) — browser/edge bundle (RAM, OPFS, S3 via presigned URLs).\n- [`@cogineai/mafs-server`](../server) — `mafs-daemon` HTTP server.\n- [`@cogineai/mafs-agents`](../agents) — adapters for OpenAI / Vercel / LangChain / Mastra / pi.\n\n## License & attribution\n\nApache-2.0. MAFS is a fork of [Mirage](https://github.com/strukto-ai/mirage); see the project-level [`NOTICE`](https://github.com/cogine-ai/CogineX-mono/blob/main/packages/mafs/NOTICE) for attribution and the relationship to upstream.\n","readmeFilename":"README.md"}