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

# Get started with Portal CLI

Portal CLI gives you terminal access to Portal. You can run the latest release
with `npx`, so you do not need to install it globally.

## Prerequisites

Before you start, make sure you have:

* Access to a Portal instance
* Your Portal instance URL, such as `https://portal.example.com`
* CLI authentication enabled in your Portal backend through CIMD. For a hosted
  Portal instance, ask your Portal administrator to
  [enable CIMD](../mcp/connecting-agents#admin-enabling-cimd) before you run
  `auth login`.
* [Node.js](https://nodejs.org/) 24 and npm

## Connect to Portal

<Steps>
  <Step title="Run Portal CLI">
    Check the latest published version:

    ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
    npx @spotify/portal-cli@latest --version
    ```

    `npx` downloads and runs the latest release without adding a global
    installation.
  </Step>

  <Step title="Authenticate">
    Sign in with your Portal instance URL:

    ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
    npx @spotify/portal-cli@latest auth login \
      --backend-url https://portal.example.com
    ```

    The command opens a browser for authentication. If the environment cannot
    open one, add `--no-browser` and open the printed authorization URL
    yourself.
  </Step>

  <Step title="Verify the instance">
    List your configured instances:

    ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
    npx @spotify/portal-cli@latest auth list
    ```

    The Portal instance you just authenticated with should be selected.
  </Step>

  <Step title="Run your first Portal workflow">
    Run a bounded search across the software catalog and TechDocs:

    ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
    npx @spotify/portal-cli@latest search onboarding --limit 5 --json
    ```

    This is read-only. A successful response is a JSON document with `items`,
    `totalItems`, and `pageInfo`. An empty `items` array still means the command
    succeeded; try a term used by your organization.
  </Step>
</Steps>

## Use Portal with a coding agent

The [Portal AI plugins](https://github.com/spotify/portal-ai-plugins) add Portal
workflows to Claude Code, Codex, and Cursor. The plugins use Portal CLI for
setup, diagnostics, search, service briefings, and Portal actions.

<Tabs>
  <Tab title="Claude Code">
    Add the marketplace and install the plugin:

    ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
    claude plugin marketplace add spotify/portal-ai-plugins
    claude plugin install portal@portal
    ```

    Start a new Claude Code session, then run:

    ```text theme={"theme":{"light":"github-light","dark":"dracula"}}
    /portal:setup
    ```
  </Tab>

  <Tab title="Codex">
    Add the marketplace, then open Codex:

    ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
    codex plugin marketplace add spotify/portal-ai-plugins
    codex
    ```

    Open `/plugins`, install **Spotify Portal**, and start a new task. Then ask:

    ```text theme={"theme":{"light":"github-light","dark":"dracula"}}
    Set up Spotify Portal for me.
    ```
  </Tab>

  <Tab title="Cursor">
    Register the
    [`spotify/portal-ai-plugins`](https://github.com/spotify/portal-ai-plugins)
    repository in your Cursor team marketplace. Install **Spotify Portal** from
    **Cursor Settings → Plugins**. Cursor uses the shared Portal CLI workflows.
  </Tab>
</Tabs>

After setup, ask your coding agent to search Portal, inspect a service, or find
an action. See the
[plugin repository](https://github.com/spotify/portal-ai-plugins#workflows) for
the available workflows and host-specific usage.

## Log out

Clear the stored credentials for one instance:

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
npx @spotify/portal-cli@latest auth logout --instance portal.example.com
```

Run `auth login` again when you want to reconnect.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The server does not support CLI authentication">
    If `auth login` reports that the server does not support CLI authentication,
    the Portal backend does not expose the CIMD metadata that the CLI needs.
    Ask your Portal administrator to enable **Client ID metadata documents**
    under **App Settings > General > MCP**, then retry the command. For a hosted
    Portal instance, this setting is managed by the instance administrator.
  </Accordion>

  <Accordion title="Authentication fails or the browser does not open">
    Confirm the Portal instance URL, then retry without opening a browser
    automatically:

    ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
    npx @spotify/portal-cli@latest auth login \
      --backend-url https://portal.example.com \
      --no-browser
    ```

    Open the printed authorization URL yourself. If access is denied, confirm
    that you can sign in to the Portal instance in your browser.
  </Accordion>

  <Accordion title="The CLI uses the wrong instance">
    List the configured instances, select the intended one, and verify it:

    ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
    npx @spotify/portal-cli@latest auth list
    npx @spotify/portal-cli@latest auth select --instance portal.example.com
    npx @spotify/portal-cli@latest auth show --instance portal.example.com
    ```
  </Accordion>

  <Accordion title="A command is unavailable">
    Inspect the latest published command help:

    ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
    npx @spotify/portal-cli@latest --help
    npx @spotify/portal-cli@latest <command> --help
    ```

    The help output for the latest release is the authoritative source for
    available commands and flags.
  </Accordion>
</AccordionGroup>

## Next steps

* View [`@spotify/portal-cli` on npm](https://www.npmjs.com/package/@spotify/portal-cli).
* Explore the [Portal AI plugins](https://github.com/spotify/portal-ai-plugins).
* Use `npx @spotify/portal-cli@latest <command> --help` for the
  authoritative help for the latest release.