> ## 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.

# Local Resource Management From AI Explorer

The Portal CLI provides commands to discover, install, and manage AI Explorer resources directly from your terminal. You can browse available rules and skills, install them into your project for use with Claude Code, Cursor, or Codex, and remove them when no longer needed.

## Authentication

The `list` and `install` commands require authentication with your Portal instance. Sign in first:

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
portal-cli auth login
```

The `remove` command operates locally and does not require authentication.

## Commands

### `portal-cli ai list`

Browse available rules and skills from your Portal instance.

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
portal-cli ai list
portal-cli ai list --type rule --discipline backend
portal-cli ai list --certified-only --limit 50
```

| Flag               | Default  | Description                                  |
| ------------------ | -------- | -------------------------------------------- |
| `--type`           | `all`    | Resource type: `skill`, `rule`, or `all`     |
| `--discipline`     |          | Filter by disciplines (comma-separated)      |
| `--category`       |          | Filter by categories (comma-separated)       |
| `--owners`         |          | Filter by owners (comma-separated)           |
| `--certified-only` | `false`  | Only show certified resources                |
| `--limit`          | `20`     | Maximum results per type                     |
| `--format`         | `claude` | Agent format: `claude`, `cursor`, or `codex` |
| `--json`           | `false`  | Output as machine-readable JSON              |

#### Listing installed resources

Use `--installed` to see what's already installed locally instead of querying the remote catalog:

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
portal-cli ai list --installed
portal-cli ai list --installed --format cursor
```

This scans the appropriate directories for your chosen format (e.g. `.claude/rules/`, `.claude/skills/` for Claude) and identifies which resources were installed through the CLI.

### `portal-cli ai install`

Install rules and skills into your project. Provide one or more entity refs:

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
portal-cli ai install --id aicontext:default/my-rule
portal-cli ai install --id aicontext:default/my-rule,aicontext:default/my-skill
portal-cli ai install --id aicontext:default/my-rule --id aicontext:default/my-skill
```

| Flag       | Default   | Description                                          |
| ---------- | --------- | ---------------------------------------------------- |
| `--id`     | required  | Entity refs to install (repeatable, comma-separated) |
| `--format` | `claude`  | Agent format: `claude`, `cursor`, or `codex`         |
| `--scope`  | `project` | Install location: `project` or `user`                |
| `--json`   | `false`   | Output as machine-readable JSON                      |

#### Where files are written

The install location depends on your chosen format and scope:

| Format   | Rules path              | Skills path              |
| -------- | ----------------------- | ------------------------ |
| `claude` | `.claude/rules/<id>.md` | `.claude/skills/<name>/` |
| `cursor` | `.cursor/rules/<id>.md` | `.cursor/skills/<name>/` |
| `codex`  | `.codex/rules/<id>.md`  | `.agents/skills/<name>/` |

* **Project scope** (default) writes relative to your project root (the nearest parent directory containing `.git`).
* **User scope** (`--scope user`) writes relative to your home directory, making resources available across all projects.

### `portal-cli ai remove`

Remove previously installed resources:

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
portal-cli ai remove --id aicontext:default/my-rule
portal-cli ai remove --id aicontext:default/my-rule,aicontext:default/my-skill
```

| Flag       | Default  | Description                                         |
| ---------- | -------- | --------------------------------------------------- |
| `--id`     | required | Entity refs to remove (repeatable, comma-separated) |
| `--format` | `claude` | Agent format: `claude`, `cursor`, or `codex`        |
| `--json`   | `false`  | Output as machine-readable JSON                     |

The remove command searches both project and user scopes for matching resources. It only removes files that were installed through the CLI — manually created rules and skills are left untouched.

## Managed files

When the CLI installs a resource, it adds a `portal` block to the file's YAML frontmatter:

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
---
title: My Rule
portal:
  managed: true
  downloadedAt: '2026-07-23T12:00:00.000Z'
  entityRef: aicontext:default/my-rule
---
```

This metadata lets the CLI:

* **Identify Portal-managed files** — the `remove` command only deletes files with `managed: true`, protecting your manually authored resources
* **Track provenance** — `list --installed` reads the `entityRef` to show which catalog entity each file came from
* **Record install time** — `downloadedAt` shows when the resource was last installed