jfrog

What this skill does

# JFrog Skill

The foundational skill for all JFrog agent interactions. Covers JFrog Platform concepts, `jf` CLI setup and authentication, and intent routing to workflow skills.

Interact with the JFrog Platform through the JFrog CLI (`jf`) and, where the
CLI falls short, through REST APIs and GraphQL. In code examples below,
`<skill_path>` refers to this skill's directory and is resolved automatically
by the agent. If the agent does not resolve it, determine the path by locating
this SKILL.md file and using its parent directory.

## Prerequisites

The following tools must be available on `PATH`:

| Tool | Purpose |
|------|---------|
| `curl` | HTTP requests to JFrog REST and GraphQL APIs |
| `jq` | JSON parsing of CLI and API output |

## Environment check

Before your first JFrog operation in a session, run the environment check.
It verifies the CLI is installed, checks for updates, and exports
`JFROG_CLI_USER_AGENT` so every outbound request is identifiable:

```bash
eval "$(JFROG_SKILL_MODEL="<model-slug>" bash <skill_path>/scripts/check-environment.sh)"
```

Set `JFROG_SKILL_MODEL` to the model slug you are running as (e.g.
`opus-4.6`, `sonnet-4`). The script appends it to the user agent string.

The `eval` is required — the script outputs
`export JFROG_CLI_USER_AGENT='model/<model-slug> jfrog-skills/<version> jfrog-cli-go/<cli-version>'`
on stdout. The JFrog CLI picks this up natively and injects it as the
`User-Agent` header on every HTTP request. JSON state is printed to stderr
for informational purposes (also written to the cache file).

The script uses a 24-hour cache at `<skill_path>/local-cache/jfrog-skill-state.json`. If the
cache is fresh, it returns immediately. If stale or missing, it checks whether
`jf` is installed, its version, and whether a newer version is available.

- Exit 0: cache is fresh, CLI is ready
- Exit 1: cache was stale and has been refreshed, CLI is ready
- Exit 2: `jf` is not installed

Bypass the cache only when the user explicitly asks to install, upgrade, or
reconfigure the CLI.

If the CLI is missing (exit 2) or an upgrade is needed, read
`references/jfrog-cli-install-upgrade.md` for install and upgrade instructions.

### JSON parsing (`jq`)

Use **`jq`** for all JSON parsing of CLI and API output (pipes, `-r`, filters).
Examples: `base64 -d | jq -r '.url'`, `jf rt curl ... | jq '.[] | .key'`.

## Network permissions

JFrog servers are not on the default sandbox network allowlist. Every Shell
call that contacts a JFrog server — whether via `jf` CLI, `jf rt curl`,
`jf xr curl`, or plain `curl` — requires `required_permissions: ["full_network"]`.

Without this permission, commands fail silently: `jf` exits with code 1 and
empty output, `curl` returns an empty response, and downstream JSON parsing
crashes. All JFrog operations that touch the network need this permission.

### Agent execution environments

`check-environment.sh` does **not** call your JFrog server, but it may make an
outbound request to `releases.jfrog.io` for version checking and may **write**
`<skill_path>/local-cache/jfrog-skill-state.json` when the cache is stale. In a **sandboxed**
agent environment, **`full_network` alone may not suffice**: if the workspace
cannot be written, the check can fail before any JFrog call. Request
permissions that allow writing `<skill_path>/local-cache` (or run
outside a restrictive sandbox) when you see filesystem errors from the
environment check.

### `local-cache/` — allowed files only

`<skill_path>/local-cache/` is **not** a general scratch or temp directory. Use
it **only** for these two artifacts:

1. **`jfrog-skill-state.json`** — written by `scripts/check-environment.sh`
   (24-hour CLI check cache).
2. **`onemodel-schema-${JFROG_SERVER_ID}.graphql`** — cached OneModel supergraph
   schema (see `references/onemodel-graphql.md`).

**Do not** save HTTP response bodies, GraphQL query results, ad-hoc JSON, reports,
or any other temporary files under `local-cache/`. Write those to a host temp
path instead (for example `/tmp/<name>-$$.json` or `mktemp -d`), echo the path
when a follow-up Shell step must read the file — same pattern as *Preserving
command output* below.

Apply `full_network` on the **first** Shell call that hits JFrog. Once
granted for a session, the agent environment typically retains it for
subsequent calls, but always include it explicitly to avoid silent failures.

## Server management

Server configuration is always read live from `jf config` (never cached).

- **List servers**: `jf config show` (local operation, no network needed)
- **Use a specific server**: pass `--server-id <id>` to any command
- **Switch default**: `jf config use <server-id>`
- **Add a new server**: read `references/jfrog-login-flow.md` for the full
  login procedure (web login or manual token setup)

### Server selection rules (mandatory)

Exactly one server (or an explicit set of servers) must be resolved before any
operation. The rules are strict and apply to every CLI command, API call, and
subagent prompt:

1. **User named specific server(s)** — use those and only those. Pass
   `--server-id <id>` (CLI) or the matching server-id to
   `get-platform-credentials.sh` (REST). Do not touch any other configured
   server.
2. **User did not name a server** — use the current default server and only
   it. Determine the default via `jf config show` (the entry marked as
   default). If no default is set, stop and ask the user which server to use.
3. **Verify before executing** — after resolving the server, confirm it
   exists in `jf config show` output before running any command against it.
   If the server-id is not listed, stop and tell the user.

Do not fall back to a different server. Silently switching servers is
dangerous because different servers hold different data, permissions, and
configurations — an operation that succeeds on the wrong server can corrupt
state, leak data across environments, or produce results the user cannot
reproduce. If the resolved server produces any error — does not exist in
`jf config`, authentication failure (401/403), network error, connection
refused, or any other failure — stop immediately and report the error to the
user. Do not try other configured servers, do not iterate through the server
list, and do not silently switch servers. Ask the user how to proceed.

## Command discovery

Use the commands listed below as your primary reference. Run `--help` to
verify options you are unsure about or to discover commands not listed here —
do not rely on memorized commands outside this skill, as they may be outdated.

1. `jf --help` — list all namespaces and top-level commands
2. `jf <namespace> --help` — list subcommands in a namespace
3. `jf <command> --help` — show usage, arguments, and options

### CLI namespaces

| Namespace | Alias | Product |
|-----------|-------|---------|
| `rt` | | Artifactory |
| `xr` | | Xray |
| `ds` | | Distribution V1 |
| `at` | `apptrust` | AppTrust |
| `evd` | | Evidence |
| `mc` | | Mission Control |
| `worker` | | Workers |
| `config` | `c` | CLI server configuration |
| `plugin` | | CLI plugin management |
| `ide` | | IDE integration |

> **Sunset notice:** JFrog Pipelines has been sunset and is no longer supported.
> Do not use the `pl` CLI namespace or the Pipelines REST API
> (`/pipelines/api/...`). If a user asks about Pipelines, inform them the
> product has been sunset.

Top-level lifecycle commands (no namespace): `rbc`, `rbp`, `rbd`, `rba`,
`rbf`, `rbe`, `rbi`, `rbs`, `rbu`, `rbdell`, `rbdelr`.

Top-level security commands: `audit`, `scan`, `build-scan`, `curation-audit`,
`sbom-enrich`.

Top-level other: `access-token-create` (`atc`), `login`, `how`, `stats`,
`generate-summary-markdown`, `exchange-oidc-token`, `completion`.

## Artifactory operations

Artifactory resources are managed through the `jf rt` namespace — repos, files,
builds, permissions, users/groups, and replication. Read
`references/artifactory-operations.md` when performing any