{"id":103320,"plugin_id":"plugin_asdk_app_6aedf6ea2fac819180910f8b98663c77","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-18T06:19:20.513Z","digest":"02f5eeaf9c5f45c967bb6102f520f42cdbb0f0d84e50fb3d49918989b8681bf2","against":null,"payload":{"description":"Clay CLI setup — install, repair, and authenticate the Clay command-line interface. Use when the user requests CLI setup or the clay entry skill selects CLI access and requires setup. Do not trigger solely because the clay executable is missing; consult the clay entry skill to choose the access method first.","included_files":[{"relative_path":"cursor-install.md","size_in_bytes":9875}],"name":"cli-setup","skill_md_contents":"---\nname: cli-setup\ndescription: Clay CLI setup — install, repair, and authenticate the Clay command-line interface. Use when the user requests CLI setup or the clay entry skill selects CLI access and requires setup. Do not trigger solely because the clay executable is missing; consult the clay entry skill to choose the access method first.\nallowed-tools: Bash(clay --version), Bash(clay whoami), Bash(echo \"exit_code=$?\"), Bash(clay login), Bash(clay login --device), Bash(npm list --global --depth=0), Read\n---\n\n# Clay CLI setup\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\n## 0. Check whether the task needs CLI setup\n\nContinue with this skill when the user asks to install or sign into the CLI,\nasks to fix plugin registration (for example, a Cursor plugin that never appears), or\nthe task uses the CLI. Honor the user's choice of CLI even when Clay MCP tools are\nconnected. First check your available tools for Clay MCP tools. When they are\nconnected and the user hasn't asked for the CLI, stop and return to the skill you came\nfrom. When they are connected and the user asked to run operations with the CLI but not\nto install or sign in to it, ask before installing or signing in: CLI sign-in needs the\nuser to approve it in a browser, and the connected tools can run the same operations\nnow. A missing, outdated, or signed-out `clay` executable does not affect the MCP\nsession.\n\nInstall the CLI independently of the plugin, then check authentication. The same flow\napplies to Claude Code, Codex, Cursor, and Cowork. Keep existing credentials and the\nuser's installation method when upgrading.\n\n## 1. Check current state\n\nResolve `<PLUGIN_ROOT>` as two levels above this skill's directory. Use that exact\nplugin copy, not whichever older cache directory was most recently modified.\n\n```bash\nbash \"<PLUGIN_ROOT>/scripts/check-cli.sh\" plain\ncat \"<PLUGIN_ROOT>/cli-min-version\"\n```\n\nThe check is local and does not sign in or download anything. A missing, old, or\nplugin-managed CLI needs step 3, even if an old cached launcher still works. The\nmetadata is a minimum supported version, not an exact pin: leave a newer independent\nCLI installed. If the check prints nothing, the installed CLI is compatible; proceed\nto the authentication check below.\n\nFor a reported Cursor plugin registration problem, do step 2 even when the CLI works.\n\n## 2. Cursor only: resolve which plugin install path applies\n\nSkip this section unless installing the plugin into Cursor or investigating a plugin\nthat never appears in Settings → Plugins. Read `cursor-install.md` in this directory\nand follow its policy checks before choosing marketplace import or local sideload.\nA working CLI alone does not prove that Cursor loaded the plugin. If policy blocks\ninstallation, follow that guide's admin handoff; do not bypass the policy.\n\n## 3. Install or migrate the CLI\n\n```bash\nbash \"<PLUGIN_ROOT>/scripts/install-cli.sh\" --version \"$(cat \"<PLUGIN_ROOT>/cli-min-version\")\"\n```\n\nFor a missing CLI or a recognized old plugin forwarder, this installs a native\nmacOS/Linux executable at `~/.local/bin/clay`, verifying its checksum and version.\nFor an existing native CLI below the minimum, it invokes that executable's `update`\ncommand instead of reinstalling it. It checks `~/.local/bin/clay` even when that\ndirectory is outside PATH and preserves compatible or newer versions. An existing\nnpm install keeps using npm. It never changes credentials.\n\nIf the user's organization requires Node-based execution, or the user explicitly\nchooses npm, use this alternative (requires Node 22.21+ within Node 22 and npm):\n\n```bash\nbash \"<PLUGIN_ROOT>/scripts/install-cli.sh\" --method npm --version \"$(cat \"<PLUGIN_ROOT>/cli-min-version\")\"\n```\n\nDo not silently switch methods after a failed download or checksum check. If a native\nbinary is blocked by enterprise allowlisting, explain that the Node-based install is\navailable and use it when the user chooses that path. If npm reports a conflicting\n`@claypi/cli` installation, inspect `npm list --global --depth=0` and its executable\npath; migrate that old package explicitly rather than forcing an overwrite.\n\nRead the installer's printed executable path. If its directory is missing from PATH,\nadd it once to the appropriate startup file for the user's shell (for example `.zshrc`\nfor zsh or `.bashrc` for interactive bash). Inspect the existing configuration first;\ndo not append to every shell's startup file or duplicate an existing entry. For the\ndefault native location, the line is `export PATH=\"$HOME/.local/bin:$PATH\"`.\n\nUse the printed **absolute executable path** for all remaining commands in this\nsession, including subsequent skill calls, if the agent's inherited PATH is stale.\nVariables do not persist between shell tool calls. Do not require a restart just to\nfinish setup. Resolve any older executable shadowing this path before declaring PATH\nconfigured; do not delete unrelated executables.\n\nVerify the executable with `--version` and compare its semver (before `+<commit>`)\nto `cli-min-version`. Then run `clay whoami; echo \"exit_code=$?\"`, substituting the\nverified absolute path when necessary:\n\n- **0** with a user/workspace object: keep the session; skip sign-in and go to step 5.\n- **3** (`auth_*`): go to step 4.\n- **5** (`network_*`): investigate the network and `CLAY_API_URL`; do not restart sign-in.\n- Any other failure: diagnose it before proceeding.\n\n## 4. Sign in when needed\n\nUse the verified executable from step 3, including its absolute path when PATH has not refreshed. Run `clay login`. It opens a browser, the user signs in and picks\nthe workspaces to connect, and the CLI stores a session per workspace locally on disk and\nre-reads it on every command, so there's nothing else to configure and no restart to follow it.\nLater commands run against the first workspace selected, and `clay workspaces switch <id>` moves\nbetween them. The flow waits up to 5 minutes for the browser round-trip. If your shell tool lets\nyou set a per-command timeout, request at least 5 minutes and just run it directly and block on\nit:\n\n```bash\nclay login   # request a timeout of at least 5 minutes if your tool supports one\n```\n\nIf your tool's timeout can't be raised past 5 minutes and it doesn't support\nbackgrounding a long-running command, ask the user to run `clay login` in their own\nterminal instead, then poll:\n\n```bash\nclay whoami; echo \"exit_code=$?\"   # poll this until exit_code=0\n```\n\n**Codex specifically:** the shell tool's timeout is usually shorter than the\n5-minute browser round-trip, so a foreground `clay login` gets killed\nmid-sign-in. The flow itself works on a local Codex session — approved commands\nrun on the user's machine, outside the sandbox — it just has to survive the\ntimeout. The recipe:\n\n1. Run `clay login` in the background so the 5-minute wait survives the tool\n   timeout:\n\n   ```bash\n   nohup clay login >/tmp/clay-login.out 2>/tmp/clay-login.err &\n   ```\n\n2. Read the sign-in URL from `/tmp/clay-login.err` and show it to the user to open\n   in their own browser (`clay login` also tries to open the browser itself — the\n   URL is the fallback). URLs from earlier attempts won't work.\n3. Do NOT try to complete the sign-in with Codex's built-in browser tool: the user\n   isn't driving it, so their credentials aren't available to enter — and if it\n   runs in an isolated or remote context it can't reach the `127.0.0.1` callback\n   anyway, so the sign-in is throwaway.\n4. Poll `clay whoami; echo \"exit_code=$?\"` until `exit_code=0`.\n\nIf the backgrounded process dies (`clay whoami` never succeeds), fall back to the\nrun-it-in-their-own-terminal flow above.\n\nIn Cowork or another remote sandbox, use `clay login --device` and show the user the current\nverification URL and code. Do not attempt a localhost browser callback from a remote machine.\n\n## 5. Verify and onboard\n\nRun `clay whoami; echo \"exit_code=$?\"` with the verified executable. Exit 0 with a\nuser/workspace object proves authentication. Keep identity details internal unless\nneeded to resolve an account issue.\n\nIf it exits 3 after a successful login, inspect the stderr error code and\n`CLAY_CONFIG_HOME`: a different credential store or stale key can cause this. Retry\nlogin as appropriate; this is not evidence of a workspace-role problem. Preserve\nexisting credentials during installation and migration.\n\nIf `whoami` or login reports `onboarded: false`, follow the `onboard` skill. Continue\nusing the verified absolute CLI path there if needed. If this session has not loaded\nthe skill yet, read `<PLUGIN_ROOT>/skills/onboard/SKILL.md` directly. Otherwise setup\nis complete; do not make the user authenticate again merely because the plugin updated.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}