> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCLIs

> Discover, install, update, inspect, authenticate, and integrate AI-native CLI packages, skills, and MCP servers.

OpenCLIs is the package and discovery platform for the Monolex CLI estate. It
resolves signed registry/CDN releases, installs first-party and supported GitHub
Release tools, tracks local package state, deploys agent skills from each
tool's `initiate/` bundle, and registers compatible binaries as MCP servers in
AI clients.

*Published contract: `openclis 0.4.18`, CDN build
`2026-07-15-182615`. The executing binary, registry response, and public CDN
metadata agree on this release.*

*Registry ownership: the canonical `docs_url` is this page, the public product
homepage is `https://openclis.com`, and OpenCLIs pairs with NIIA, OpenCLIs
Vault, Monogram, and Monosystem. Repository ownership remains
`monolex/openclis`; no public source URL is advertised while that repository is
private.*

Version 0.4.18 keeps native MCP registration as the default and the
`niia mcp-serve` adapter behind an explicit `--wrap` choice. It adds scoped,
non-mutating update plans with the stable `openclis.update-plan.v1` JSON schema
and makes selected install failures propagate as a non-zero command result.

<Warning>
  `openclis update` still executes immediately unless `--dry-run` is present.
  Version 0.4.18 provides a real read-only plan; `--json` is valid only with
  `--dry-run`. Bare `update` and explicit `--all` select every installed
  non-keychain tool, while named tools form an exact scope. `--all` cannot be
  combined with explicit tool names.
</Warning>

## Quick Start

```bash theme={null}
curl -fsSL https://openclis.com/install.sh | sh

openclis --version
openclis search "code search"
openclis install monogram
openclis list --json
openclis init monogram
```

## Package Commands

| Command                                          | What it does                                                                                                                                    | Effect or release boundary                                              |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `ensure <tool> [tool...]`                        | Leaves already available tools alone and installs only missing tools.                                                                           | Idempotent availability check with installation effects for misses.     |
| `search <query>`                                 | Searches the OpenCLIs registry by name, description, and category.                                                                              | Registry discovery; does not install.                                   |
| `install <tool>`                                 | Downloads the current platform artifact, verifies the package contract, installs its binaries, and deploys enabled skills.                      | Executable and configuration mutation.                                  |
| `install @github/<owner/repo>`                   | Installs a supported tool such as ripgrep, fd, bat, jq, or gh from GitHub Releases.                                                             | Third-party provenance remains GitHub, not a first-party Monolex build. |
| `install @official/<tool>` / `@npm/<package>`    | Installs an official distribution or npm-backed CLI through its owning source adapter.                                                          | Provenance and version semantics remain source-specific.                |
| `update [--all \| <tool>...]` / `upgrade`        | Applies available updates to every installed non-keychain tool or an exact named scope.                                                         | Executes immediately; `--all` and named tools are mutually exclusive.   |
| `update --dry-run [--json] [--all \| <tool>...]` | Resolves the same scope without installing and reports updates, current tools, unavailable metadata, missing names, and skipped keychain tools. | `--json` emits `openclis.update-plan.v1`; no executable is replaced.    |
| `update --force-downgrade <tool>`                | Accepts a registry/CDN version regression as a deliberate rollback.                                                                             | Destructive version transition; verify artifact and runtime afterward.  |
| `list`                                           | Shows installed package names, versions, builds, binaries, and local state.                                                                     | Add `--json` for durable inventory automation.                          |
| `info <tool>`                                    | Joins installed state with current registry metadata and release history.                                                                       | Read-only package diagnosis.                                            |
| `rollback <tool>`                                | Reinstalls the release pointed to by the package's public previous-release metadata.                                                            | Executable downgrade; verify the resulting version and build.           |
| `uninstall <tool>` / `remove`                    | Removes the installed package entry and deployed binary links.                                                                                  | Package removal; separately managed external state may remain.          |
| `reinstall <tool>`                               | Re-deploys cached skills/integration files for an installed tool.                                                                               | Local integration mutation; it is not a network version upgrade.        |
| `status`                                         | Prints the installed estate and writes `~/.openclis/status.json` plus `status.md`.                                                              | Inventory read with generated status-file writes.                       |
| `version` / `--version`                          | Prints the executing OpenCLIs version.                                                                                                          | Read-only binary identity.                                              |
| `license [tool]` / `--license`                   | Prints the platform EULA or the selected tool's license information.                                                                            | Read-only legal metadata.                                               |

Installed package metadata, executable payload identity, source-tree version,
and public CDN release are separate surfaces. For release verification, check
all of these rather than treating `openclis list` as proof that the executable
actually reports the same version.

## AI Guide and Skill Deployment

| Command                    | What it does                                                            | Output or effect                                  |
| -------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------- |
| `init` / `initiate`        | Runs the same installed-estate status generation as `status` in 0.4.18. | Writes `~/.openclis/status.json` and `status.md`. |
| `init <tool>`              | Prints the available AI usage guide for one installed package.          | Read-only progressive-disclosure surface.         |
| `config get <key>`         | Reads one OpenCLIs setting using dot notation.                          | Read-only.                                        |
| `config set <key> <value>` | Writes one setting.                                                     | Persistent OpenCLIs configuration mutation.       |

Tools with an `initiate/` directory can deploy both `SKILL.md` and
`initiate.md`. Standard targets are:

| Key                    | Default target                                                 |
| ---------------------- | -------------------------------------------------------------- |
| `skill_targets.claude` | `~/.claude/skills/`                                            |
| `skill_targets.agents` | `~/.agents/skills/`                                            |
| `skill_targets.gemini` | `~/.gemini/skills/`                                            |
| `skill_targets.<name>` | Custom target or `false` to disable it                         |
| `auto_skill`           | Enables or disables automatic deployment during install/update |

```bash theme={null}
openclis config set skill_targets.agents true
openclis config set skill_targets.gemini true
openclis config set auto_skill true
```

## MCP Registration

| Command                            | What it does                                                                                                         | Effect                                                      |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `mcp add <tool> --<target>`        | Registers the installed tool's native MCP stdio server in the chosen AI CLI.                                         | Mutates that client's MCP configuration.                    |
| `mcp add <tool> --wrap --<target>` | Registers `niia mcp-serve <tool>` as an explicit adapter instead of the native server.                               | Adapter choice is visible and intentional.                  |
| `mcp remove <tool> --<target>`     | Removes that registration.                                                                                           | Client configuration mutation; does not uninstall the tool. |
| `mcp list [--json]`                | Shows registered MCP servers across supported AI CLIs, including transport, scope, command or URL, and adapter mode. | Read-only integration inventory.                            |

```bash theme={null}
openclis mcp add kernel-cli --claude
openclis mcp add monogit --wrap --codex
openclis mcp list --json
openclis mcp remove kernel-cli --claude
```

Supported targets in 0.4.18 are `--claude`, `--claude-desktop`, `--gemini`,
`--codex`, `--opencode`, and `--crush`. Native registration and wrapping are
different execution paths; use `--wrap` only when the adapter is the intended
contract.

CLI help/schema parity and actual MCP runtime transport are distinct gates.
After registration, start the target AI client and call a harmless read-only MCP
tool before declaring the integration live.

## Account and Vault Commands

| Command                                                     | What it does                                                                | Security effect                                                                    |
| ----------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `login [api-key]`                                           | Authenticates OpenCLIs and stores the resulting credential.                 | Avoid exposing positional keys through shell history; prefer the interactive flow. |
| `whoami`                                                    | Shows the authenticated account identity.                                   | Read-only.                                                                         |
| `logout`                                                    | Revokes authentication and clears the corresponding vault state.            | Credential mutation.                                                               |
| `vault store <service>`                                     | Sends stdin to the stable vault helper.                                     | Secret write.                                                                      |
| `vault read <service>`                                      | Reads a token through the vault helper.                                     | Secret-bearing stdout; never include in logs.                                      |
| `vault delete <service>`                                    | Deletes one service credential.                                             | Irreversible credential removal.                                                   |
| `vault list`                                                | Lists service names without printing token values.                          | Safe inventory view.                                                               |
| `auth read\|write\|delete\|read-json\|write-json <service>` | Provides the lower-level structured credential bridge used by integrations. | Secret-bearing compatibility surface; prefer `vault` for routine human use.        |

The vault subcommands delegate to the separately released
[`openclis-vault`](/ai-clis/openclis-vault) binary so routine OpenCLIs updates
do not change the macOS Keychain caller identity.

## Direct Tool Wrapper

If a top-level word is not an OpenCLIs built-in, OpenCLIs can resolve it as an
installed tool and forward the remaining arguments:

```bash theme={null}
openclis ripgrep --version
```

The child tool owns its stdout, stderr, exit code, and command semantics. For
automation that needs an unambiguous executable identity, invoking the installed
binary directly remains the clearer contract.

## Release Verification Pattern

```bash theme={null}
command -v openclis
openclis --version
openclis list --json
curl -fsSL https://cdn.openclis.com/openclis/latest.json
```

For a tool, also run its own `--version`, `--help`, doctor/status command, and a
real read-only smoke. Registry installation success is only the package layer.

## Relationships

| Tool                                      | Ownership                                                                                                       |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [OpenCLIs Vault](/ai-clis/openclis-vault) | Stable keychain helper for tokens and shared service credentials                                                |
| [MonoPass](/ai-clis/monopass)             | Structured passkey/WebAuthn store rather than general package authentication                                    |
| [NIIA](/ai-clis/niia)                     | Uses installed tools for orchestration and can wrap registered MCP services as CLI calls                        |
| [Monosystem](/ai-clis/monosystem)         | Uses `openclis.update-plan.v1` for scoped remote plans and applies only behind the target device's upgrade gate |
| [Kernel CLI](/kernel-cli)                 | Example dual CLI/MCP package installed and registered by OpenCLIs                                               |