Terminal
Terminal/Skill
Configures npm, pip, Maven and other package managers to use your JFrog Artifactory repository, using the repo the workspace resolver picks.
By JFrog
Works with
npx skills add jfrog/jfrog-skills --skill jfrog-setup-package-managersIn examples below, <skill_path> is this skill's directory (parent of
scripts/ / references/).
Apply the session hook's repo pick via jf setup,
then record it in .jfrog/local/package-resolution.json
via scripts/merge-workspace-binding.sh.
jf setup writes package-manager-native config (.npmrc, pip.conf, uv.toml, …); the binding
lets the hook re-apply on later sessions.
Every jf setup this session:
../jfrog/SKILL.md At-a-glance / Tier A
(Step 0.1) → <UA>, --server-id placement, single-server, stop-don't-switch.
Prefer full base SKILL.md when you can; Tier B (cli-gotchas / jf-api / …)
only if the next action needs jf api / advanced CLI--repo + --server-id. <repoKey> ← Step 2
(table / binding / global-cache) or user override / unresolved AskQuestion;
never self-discover. <SID> ← resolver only (never user-selected)jf setup unless user asked silent / non-interactiveabort (2-answer cap).jfrog/local/package-resolution.json../jfrog/SKILL.md Cautious execution / Server selection / Tier A
gotcha floor). Full cli-gotchas.md is Tier B — not required for jf setupSession-start hook: resolves repo keys per package type, injects the
"Resolved URLs for this session" table, refreshes the global cache. The same
renderer is available on demand via modules/package-resolution/scripts/print-policy.mjs (the enforce
notice embeds the exact command), so the policy can be loaded after setup.
This skill: reads that output, runs jf setup, and persists the workspace
binding at .jfrog/local/package-resolution.json (via
scripts/merge-workspace-binding.sh) when package-manager config is still missing.
Honor the injected policy's governed scope. The session policy lists the
package managers it governs. Do not proactively onboard a package manager the policy
doesn't govern (e.g. a stray Dockerfile when only pypi/npm are governed) —
those are intentionally out of scope. An explicit user request to set up any
package manager still works (Step 1's user-mention signal and Step 2's AskQuestion for an
unlisted package manager apply as usual).
jf setup mutates user state (~/.npmrc, ~/.docker/config.json, …).
Confirm before the first jf setup in a session unless the user explicitly
requests silent/non-interactive setup.Out of scope: CLI install/login (../jfrog/references/…).
Not tips. Do/don'ts and known traps for jf setup — follow every bullet
before binding. Also honor base Tier A hard rules from
../jfrog/SKILL.md (Cautious execution, Server selection,
Tier A gotcha floor). Full cli-gotchas.md is Tier B — load only if this
session also needs jf api / advanced CLI.
--repo and --server-id — omitting --repo fails when
multiple repos match. See jf-setup-command.md.jf setup overwrites package-manager config without backup — skip package managers whose binding
already matches (Step 1, signal 2).jf setup docker writes creds only;
bare docker pull <img> hits Docker Hub. Complete setup, then pull via
<host>/<repoKey>/<img>..jfrog/local/package-resolution.json.jf setup,
run scripts/merge-workspace-binding.sh (Step 6). Do not hand-edit the JSON.gradle ≠ maven. Bind under repositories.gradle, never repositories.maven.| File | When to read |
|---|---|
references/jf-setup-command.md | CLI flags, supported package managers, exit-code contract, jf setup --help |
references/global-cache-file.md | Global cache shape, resolution classes, jq one-liners |
references/workspace-binding.md | Workspace binding schema, package-manager → type map, merge script |
scripts/merge-workspace-binding.sh | After each successful jf setup — deterministic binding merge (jq required) |
jf is readyjf
(even when jf is already configured). Prefer reading
../jfrog/SKILL.md in full when you can; the At-a-glance
Tier A floor is enough for jf setup / package-manager binding. Load Tier B
(cli-gotchas.md, jf-api.md, …) only if the next action needs jf api /
advanced CLI. Then run that skill's Environment check (and export
JFROG_CLI_USER_AGENT) before the first jf call.jf + a configured server (<SID>). If jf config show already
succeeds, skip to Step 1; otherwise:
jf --version missing → install per
../jfrog/references/jfrog-cli-install-upgrade.md.jf config show empty → login per
../jfrog/references/jfrog-login-flow.md
or jf config add with access-token (Bearer-only).jf setup until both succeed. Confirm before install/login.Combine four signals, in order; intersect with jf setup --help supported list:
Explicit user mention. Map aliases: python → pip/uv/pipenv (and
poetry only if the user named Poetry); java → maven/gradle; node →
npm/pnpm by lockfile (yarn only if the user named Yarn).
Workspace binding — read .jfrog/local/package-resolution.json. Drop
package managers already bound to the same key unless recovering from 401/403
(re-run same key). Package-manager → type table:
workspace-binding.md.
Workspace manifests when still ambiguous (several package managers of one
type may apply — e.g. requirements.txt and uv.lock):
| Manifest / signal | Package manager |
|---|---|
package.json, pnpm-lock.yaml | npm (+ pnpm if pnpm-lock.yaml present) |
yarn.lock (alone) | npm — do not auto-select yarn |
requirements.txt | pip |
Pipfile | pipenv |
uv.lock | uv — suppresses bare pyproject.toml → pip; keep requirements.txt + uv.lock as multi-PM |
pyproject.toml | [tool.uv] → uv; [tool.poetry] → poetry only on explicit user ask, else not applicable (do not select pip); bare PEP 621 with no uv.lock → pip |
pom.xml | maven |
build.gradle, build.gradle.kts | gradle (bind under type gradle) |
go.mod | go |
Dockerfile, compose.yaml, docker-compose.yml | docker / podman |
*.csproj, NuGet.Config | nuget / dotnet |
Chart.yaml | helm |
Binary gate (client tools only): missing client on PATH → skip as not
applicable; do not substitute another package manager or report setup
success. Exempt maven / gradle (config-only). Details:
jf-setup-command.md.
jf setup --help — filter candidates; never hardcode the list. See
jf-setup-command.md. Unsupported → report
gap, skip.
For each <package-manager>, recover <repoKey> and <serverId> from the first source
available:
<repoKey>
from URL; <serverId> from host.repositories.<type>
(gradle → repositories.gradle, not maven).global-cache-file.md.Cache disagreeing with (1)/(2) is not a reason to change the repo.
Don't choose a repo yourself: no listing, enumerating, probing, or iterating
--server-id to pick one, and don't second-guess the resolver — use resolver
output only. If the user explicitly asks to browse repos, list them via
jf api "/artifactory/api/repositories?type=virtual&packageType=<pkgType>"
(Artifactory package type from the binding map — gradle not maven;
uv / pip / pipenv / poetry → pypi), then let the user choose; the
agent still never makes the choice on its own.
Ask via AskQuestion (include the resolver/setup failure text verbatim):
No default repo for
<package-manager>on<SID>. Failure:<verbatim failure>Which Artifactory repository should I use? (repo key, orabort.)
Cap at 2 answers per package manager, then abort. User may override repo only, never server.
jf setup, persist bindingPresent the plan, one row per package manager:
<package-manager> → <repoKey> on <SID> (source: resolver)
<package-manager> → <repoKey> on <SID> (source: user-supplied)
Show binding diffs when the repo key changes.
Confirm via AskQuestion (apply / change repos / abort) unless the
user explicitly requested silent/non-interactive setup — then run directly.
Sequentially, one package manager at a time:
jf setup <package-manager> --server-id <SID> --repo <repoKey> [--project <key>]
Exit code 0 = success — merge binding (step 6). On non-zero, stop,
surface CLI output verbatim, offer alternate repo or abort (2-answer cap).
On success, run the merge script (do not hand-edit JSON). Pass the IDE workspace root when the shell cwd is not that root:
bash <skill_path>/scripts/merge-workspace-binding.sh \
--package-manager <package-manager> \
--repo <repoKey> \
[--workspace-root <workspace-root>]
Requires jq (same prerequisite as the base jfrog skill). Exit 0 prints
merged <type> → <repo> into <path>. On non-zero, stop, surface stderr
verbatim — do not claim the binding was recorded. Schema and PM → type map:
workspace-binding.md.
If this session started with the "routing NOT READY" (enforce) notice, that
notice includes a refresh command (node <plugin>/modules/package-resolution/scripts/print-policy.mjs).
After Step 3 succeeds, run that exact command and treat its stdout as the
authoritative, now-current policy — it prints the resolved Artifactory URLs and
hard rules. Continue the original request using those URLs.
If the command prints nothing, routing is off by config
(packageResolution.enabled is not true) — an admin opt-in. Report that to
the user and let them decide whether to enable it.
jf setup — checklistAt a glance invariants:
<UA> exported<repoKey> ← Step 2 or user override; <SID> ← resolver onlyjf setup <pm> --server-id <SID> --repo <repoKey>cli-gotchas.md only if Tier B path)