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

# Import your setup

> Copy the skills, plugins, MCP servers and hooks from Claude Code, Codex, Cursor or OpenCode on your machine into your Pinework workspace, picking each item.

**Import** copies the setup your coding tools already have into your Pinework workspace. It reads Claude Code, Codex, Cursor and OpenCode on your machine. You pick each skill, plugin, MCP server and hook before anything is copied.

Skills work for your agents right away. New MCP servers and hooks arrive turned off, so you choose when they start running.

## Before you start

* You need a Pinework account and a workspace.
* For the Dashboard tab, use the [Pinework Mac app](/apps/mac) with this Mac connected as a device. The browser dashboard cannot read your Mac. It shows `Config import runs in the Pinework desktop app on your Mac. This browser view is read-only.`
* For the CLI tab, install the `pinework` CLI and run `pinework login`. The CLI reads the machine it runs on.

## Copy your setup into the workspace

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step title="Open Import">
        In the Mac app, open **Settings**, then click **Import**. The screen asks **Bring your setup with you?** It lists the folders it reads: `~/.claude`, `~/.config/opencode`, `~/.codex` and `~/.cursor`.
      </Step>

      <Step title="Read this Mac">
        Click **Look on this Mac**. macOS may ask you to allow access. A progress bar shows each folder as Pinework reads it.
      </Step>

      <Step title="Pick what to bring">
        The **Pick what to bring** screen groups what it found: plugins, skills, MCP servers, hooks, commands and local folders. Untick anything you don't want. Click **Import** with the item count, such as **Import 12 items**.
      </Step>

      <Step title="Choose instructions, if asked">
        If Pinework finds a `CLAUDE.md` or `AGENTS.md`, it asks **Which instructions should your agents follow?** Pick one file and click **Use this one**. It becomes your workspace instructions and replaces any you had. Click **Skip** to keep yours.
      </Step>

      <Step title="Check where each piece went">
        The screen says **Imported** with the count. Each row says where the items landed. Plugins land in **Customize**, under **Plugins**. MCP servers and hooks say **Off until you turn them on**.
      </Step>
    </Steps>

    To bring in a second Mac, open the Mac app on that Mac and run Import there.
  </Tab>

  <Tab title="CLI">
    <Steps>
      <Step title="Go to your project">
        The CLI reads your user-level config and one project folder. The project folder defaults to the current directory. Pass `--project-dir <dir>` to read another.

        ```bash theme={null}
        cd ~/code/my-app
        ```
      </Step>

      <Step title="See what the CLI finds">
        `--source` picks the tool: `claude-code` (the default), `codex`, `cursor` or `opencode`.

        ```bash theme={null}
        pinework import scan --source claude-code --pretty
        ```

        The table lists each skill, plugin, MCP server, hook and secret name. Each row is `new`, `changed` or `same` compared with your workspace. The last line counts each status. A scan uploads names, versions and content hashes. For each MCP server, it uploads the command, args and URL. The CLI first removes URL parameters named like a key, token or password. For each hook, it uploads the event, matcher and command. It uploads no skill text, no secret value and no variable value.
      </Step>

      <Step title="Copy the items you want">
        Name items with `--only <kind>:<name>`, repeated as needed. The kinds are `skill`, `plugin`, `mcp`, `hook` and `secret`. Or take every new item with `--all-new`, and every changed one with `--all-changed`.

        ```bash theme={null}
        # Everything new, plus one changed skill
        pinework import apply --source claude-code --all-new --only skill:release-notes
        ```

        The CLI prints `Import complete.` and one count line per kind. A `changed` item updates in place. A `same` item is skipped and named.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Warning>
  `pinework import apply` with no `--only`, `--all-new` or `--all-changed` uploads nothing and exits with an error. An `--only` name that matches nothing fails the whole run, and nothing is applied.
</Warning>

## Turn on what you imported

New MCP servers and hooks arrive off. Turn on the ones you want.

<Steps>
  <Step title="Open Customize">
    In the sidebar, click **Customize**. Click the **MCP Servers** tab or the **Hooks** tab.
  </Step>

  <Step title="Enable each item">
    On each item your agents should use, click **More actions**, then **Enable**. Agents get it on their next run.
  </Step>

  <Step title="Sign in where asked">
    An imported server that needs a sign-in shows **Not connected**. Click **Connect** and finish the sign-in. See [Add an MCP server](/guides/add-an-mcp-server) for the full flow.
  </Step>
</Steps>

## How the CLI handles secrets

The CLI finds secrets in your MCP server settings, such as API keys in their `KEY=value` pairs or URLs. `import scan` lists them by name with the kind `secret`.

* **A secret you select** with `--only secret:<name>` is saved to the workspace's **Keychain**. The `Keychain:` line in the output counts it.
* **A secret you don't select** never leaves your machine. In the server's variables, a `vault:<name>` reference takes its place. Create a secret with that name before you turn the server on.
* **A secret in a server's URL** is cut from the URL, whether you select it or not.
* **A secret whose name already exists** keeps its current value. The output lists it under `Secrets kept`.

See [Secrets](/concepts/secrets) for how agents use them.

## Troubleshooting

**`Pinework isn't running on this Mac`.** The Mac app's device manager is off. Click **Start it and look again**.

**`macOS blocked <folder>`.** Allow Pinework in System Settings, under Privacy & Security, then Files and Folders. Then run the import again.

**`Nothing selected.`** You ran `import apply` with no selector. Add `--only`, `--all-new` or `--all-changed`.

**`--only matched nothing`.** The name is wrong. The error lists every name the CLI found, per kind. Copy the name from there, or from `pinework import scan`.

## Next

<CardGroup cols={2}>
  <Card title="Add an MCP server" href="/guides/add-an-mcp-server">
    Sign in to a server and turn it on for each agent.
  </Card>

  <Card title="Plugins and skills" href="/concepts/plugins-and-skills">
    What each imported piece does in a run.
  </Card>

  <Card title="Rules and instructions" href="/concepts/rules-and-instructions">
    How workspace instructions shape every agent.
  </Card>

  <Card title="Mac app" href="/apps/mac">
    Connect your Mac so agents can run on it.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.