<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Configuration, Subcommands & Options Reference - Pinner</title>
<meta name="description" content="Complete reference for Pinner CLI arguments, subcommand behaviors, environment variable authentication, cache controls, and .pinner.toml configuration schemas.">
<meta name="keywords" content="pinner options, command line arguments, configuration file schema, credentials, registry overrides, cache duration">
<link rel="canonical" href="https://ffalcinelli.github.io/pinner/configuration.html">
<link rel="icon" type="image/svg+xml" href="favicon.svg">
<meta property="og:type" content="website">
<meta property="og:url" content="https://ffalcinelli.github.io/pinner/configuration.html">
<meta property="og:title" content="Configuration & Command Reference - Pinner">
<meta property="og:description" content="Explore CLI flags, global configurations, and custom rules. Configure caching overrides, strict OSV verify checks, and multiple repository tokens.">
<meta property="og:image" content="https://ffalcinelli.github.io/pinner/favicon.svg">
<script src="https://cdn.tailwindcss.com"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
<link rel="stylesheet" href="css/style.css">
<script src="js/components.js" defer></script>
</head>
<body class="font-sans antialiased overflow-x-hidden">
<div class="hero-glow"></div>
<pinner-navbar active-page="configuration"></pinner-navbar>
<section class="relative pt-16 pb-12 hero-gradient border-b border-gray-800/40">
<div class="max-w-4xl mx-auto px-4">
<h1 class="text-4xl md:text-5xl font-extrabold text-white mb-6">
Configuration & <span class="text-sky-400">Options</span>
</h1>
<p class="text-xl text-gray-400 leading-relaxed">
A comprehensive guide to CLI flags, environment variables, and the <code>.pinner.toml</code> configuration file.
</p>
</div>
</section>
<main class="max-w-4xl mx-auto px-4 py-16 relative z-10">
<section class="mb-20" id="global-options">
<h2 class="text-2xl font-bold text-white mb-8 flex items-center">
<i class="fas fa-globe text-sky-400 mr-4"></i> Global Options
</h2>
<p class="text-gray-400 mb-8 leading-relaxed">These options can be used with any subcommand to modify Pinner's behavior.</p>
<div class="grid grid-cols-1 gap-6">
<div class="card p-6 rounded-xl">
<div class="flex flex-col md:flex-row md:items-center justify-between mb-4">
<code class="text-lg font-bold text-white">-w, --workflows <PATH></code>
<span class="text-xs text-gray-500 uppercase tracking-widest mt-2 md:mt-0">Default: Platform standard paths</span>
</div>
<p class="text-gray-400">Specify workflow files or directories to process. Can be used multiple times.</p>
</div>
<div class="card p-6 rounded-xl">
<div class="flex flex-col md:flex-row md:items-center justify-between mb-4">
<code class="text-lg font-bold text-white">-y, --yes</code>
<span class="text-xs text-gray-500 uppercase tracking-widest mt-2 md:mt-0">Flag</span>
</div>
<p class="text-gray-400">Automatically confirm all replacements without prompting. Ideal for non-interactive environments (CI).</p>
</div>
<div class="card p-6 rounded-xl">
<div class="flex flex-col md:flex-row md:items-center justify-between mb-4">
<code class="text-lg font-bold text-white">-d, --dry-run</code>
<span class="text-xs text-gray-500 uppercase tracking-widest mt-2 md:mt-0">Flag</span>
</div>
<p class="text-gray-400">Print what would be changed without actually modifying any files.</p>
</div>
<div class="card p-6 rounded-xl">
<div class="flex flex-col md:flex-row md:items-center justify-between mb-4">
<code class="text-lg font-bold text-white">--format <TYPE></code>
<span class="text-xs text-gray-500 uppercase tracking-widest mt-2 md:mt-0">Values: text, json, markdown</span>
</div>
<p class="text-gray-400">Output results in the specified format. <code>markdown</code> format is ideal for integration in PR comments.</p>
</div>
<div class="card p-6 rounded-xl">
<div class="flex flex-col md:flex-row md:items-center justify-between mb-4">
<code class="text-lg font-bold text-white">--concurrency <NUM></code>
<span class="text-xs text-gray-500 uppercase tracking-widest mt-2 md:mt-0">Default: 10</span>
</div>
<p class="text-gray-400">Number of concurrent API requests to make. Increase for large repositories, decrease to avoid rate limits.</p>
</div>
<div class="card p-6 rounded-xl">
<div class="flex flex-col md:flex-row md:items-center justify-between mb-4">
<code class="text-lg font-bold text-white">--ignore <PATTERN></code>
<span class="text-xs text-gray-500 uppercase tracking-widest mt-2 md:mt-0">Multiple</span>
</div>
<p class="text-gray-400">Actions or images to ignore (comma-separated, e.g., "actions/checkout"). Can be used multiple times.</p>
</div>
<div class="card p-6 rounded-xl">
<div class="flex flex-col md:flex-row md:items-center justify-between mb-4">
<code class="text-lg font-bold text-white">--no-cache</code>
<span class="text-xs text-gray-500 uppercase tracking-widest mt-2 md:mt-0">Flag | Conflicts with --cache-ttl</span>
</div>
<p class="text-gray-400">Disable persistent disk caching (<code>cacache</code>) and memory caching completely for this run. Forces fresh remote requests.</p>
</div>
<div class="card p-6 rounded-xl">
<div class="flex flex-col md:flex-row md:items-center justify-between mb-4">
<code class="text-lg font-bold text-white">--cache-ttl <SECONDS></code>
<span class="text-xs text-gray-500 uppercase tracking-widest mt-2 md:mt-0">Default: 3600 | Conflicts with --no-cache</span>
</div>
<p class="text-gray-400">Set the cache Time-To-Live (TTL) in seconds. Cached entries older than this duration are automatically invalidated.</p>
</div>
<div class="card p-6 rounded-xl">
<div class="flex flex-col md:flex-row md:items-center justify-between mb-4">
<code class="text-lg font-bold text-white">--offline</code>
<span class="text-xs text-gray-500 uppercase tracking-widest mt-2 md:mt-0">Flag | Conflicts with --check-osv</span>
</div>
<p class="text-gray-400">Force offline mode, preventing any network requests. Only cached dependencies can be resolved. Fails on cache misses.</p>
</div>
</div>
</section>
<section class="mb-20" id="subcommands">
<h2 class="text-2xl font-bold text-white mb-8 flex items-center">
<i class="fas fa-terminal text-sky-400 mr-4"></i> Subcommands
</h2>
<div class="space-y-8">
<div class="border-l-2 border-sky-500/30 pl-6">
<h3 class="text-xl font-bold text-white mb-2">pin</h3>
<p class="text-gray-400">Scans workflows and replaces all mutable tags with immutable commit SHAs or image digests. This is the primary command for securing your supply chain.</p>
</div>
<div class="border-l-2 border-amber-500/30 pl-6">
<h3 class="text-xl font-bold text-white mb-2">upgrade</h3>
<p class="text-gray-400 mb-2">Updates pinned dependencies to newer versions based on the subcommand-specific <code>--upgrade-strategy</code> option.</p>
<div class="text-xs text-gray-400 mb-4">
Options:
<ul class="list-disc pl-5 mt-1 space-y-1">
<li><code>--upgrade-strategy <STRATEGY></code>: Select bump strategy (<code>latest</code>, <code>major</code>, <code>minor</code>, <code>commit</code>).</li>
<li><code>-i, --interactive</code>: Prompt and select upgrades individually.</li>
</ul>
</div>
<div class="bg-amber-400/5 p-4 rounded-lg border border-amber-400/10 text-xs text-amber-400/80">
<i class="fas fa-exclamation-triangle mr-2"></i> Always review upgraded hashes to maintain security.
</div>
</div>
<div class="border-l-2 border-emerald-500/30 pl-6">
<h3 class="text-xl font-bold text-white mb-2">verify</h3>
<p class="text-gray-400 mb-2">Checks if all actions and images are pinned. Returns a non-zero exit code if unpinned dependencies are found. Perfect for CI/CD environments.</p>
<div class="text-xs text-gray-400">
Options:
<ul class="list-disc pl-5 mt-1 space-y-1">
<li><code>--check-osv</code>: Query OpenSSF OSV to fail validation if any dependency hash has known vulnerabilities (requires online connection).</li>
<li><code>--strict</code>: Fail validation if any dependency is not explicitly added to the <code>vetted</code> whitelist in <code>.pinner.toml</code>.</li>
</ul>
</div>
</div>
<div class="border-l-2 border-blue-500/30 pl-6">
<h3 class="text-xl font-bold text-white mb-2">set <ACTION> <HASH></h3>
<p class="text-gray-400">Forcibly sets a specific action or image to a provided hash across all matching occurrences in your workflows.</p>
</div>
<div class="border-l-2 border-orange-500/30 pl-6">
<h3 class="text-xl font-bold text-white mb-2">install-hook</h3>
<p class="text-gray-400">Installs a git pre-commit hook in your local repository that automatically runs <code>pinner verify</code> before every commit.</p>
</div>
<div class="border-l-2 border-teal-500/30 pl-6">
<h3 class="text-xl font-bold text-white mb-2">init</h3>
<p class="text-gray-400">Automatically initializes a <code>.pinner.toml</code> configuration file for your repository with sensible defaults.</p>
</div>
<div class="border-l-2 border-pink-500/30 pl-6">
<h3 class="text-xl font-bold text-white mb-2">export-sbom</h3>
<p class="text-gray-400">Generates and exports a Software Bill of Materials (SBOM) for all actions and container images used in your workflows.</p>
</div>
<div class="border-l-2 border-red-500/30 pl-6">
<h3 class="text-xl font-bold text-white mb-2">scan</h3>
<p class="text-gray-400 mb-2">Queries OpenSSF OSV for vulnerabilities, performs Cosign provenance verification for OCI images, and prompts to save vetted whitelists and compromised blacklists in `.pinner.toml`.</p>
<p class="text-xs text-gray-400">Supports the <code>--upgrade-strategy</code> flag to scan candidates.</p>
</div>
<div class="border-l-2 border-gray-500/30 pl-6">
<h3 class="text-xl font-bold text-white mb-2">generate-completion [SHELL]</h3>
<p class="text-gray-400">Generates shell completion scripts (Bash, Zsh, Fish, Powershell, Elvish). If the shell parameter is omitted, Pinner automatically detects your active shell environment.</p>
</div>
</div>
</section>
<section class="mb-20" id="environment-variables">
<h2 class="text-2xl font-bold text-white mb-8 flex items-center">
<i class="fas fa-key text-sky-400 mr-4"></i> Environment Variables
</h2>
<p class="text-gray-400 mb-8 leading-relaxed">Pinner automatically reads these variables for authentication, caching overrides, and API configurations.</p>
<h3 class="text-lg font-bold text-white mb-4">Authentication & APIs</h3>
<div class="overflow-x-auto rounded-xl border border-gray-800 card mb-12">
<table class="min-w-full text-left text-sm">
<thead class="bg-gray-800/50 text-white border-b border-gray-800">
<tr>
<th class="px-6 py-4 font-bold">Variable</th>
<th class="px-6 py-4 font-bold">Description</th>
</tr>
</thead>
<tbody class="divide-y divide-gray-800 text-gray-400">
<tr>
<td class="px-6 py-4 text-white font-medium"><code>GITHUB_TOKEN</code></td>
<td class="px-6 py-4">API authentication token for GitHub (bypasses low rate-limits)</td>
</tr>
<tr>
<td class="px-6 py-4 text-white font-medium"><code>GITLAB_TOKEN</code></td>
<td class="px-6 py-4">Auth token for GitLab API access</td>
</tr>
<tr>
<td class="px-6 py-4 text-white font-medium"><code>BITBUCKET_TOKEN</code></td>
<td class="px-6 py-4">Auth token for Bitbucket API access</td>
</tr>
<tr>
<td class="px-6 py-4 text-white font-medium"><code>FORGEJO_TOKEN</code></td>
<td class="px-6 py-4">Auth token for Forgejo/Gitea instances</td>
</tr>
<tr>
<td class="px-6 py-4 text-white font-medium"><code>CIRCLECI_TOKEN</code></td>
<td class="px-6 py-4">Token for CircleCI GraphQL API orb queries</td>
</tr>
<tr>
<td class="px-6 py-4 text-white font-medium"><code>PINNER_OCI_USERNAME</code></td>
<td class="px-6 py-4">Username for OCI Registries (use <code>AWS</code> for AWS ECR)</td>
</tr>
<tr>
<td class="px-6 py-4 text-white font-medium"><code>PINNER_OCI_PASSWORD</code></td>
<td class="px-6 py-4">Password or login token for OCI Registries authentication</td>
</tr>
</tbody>
</table>
</div>
<h3 class="text-lg font-bold text-white mb-4">Configuration Overrides</h3>
<div class="overflow-x-auto rounded-xl border border-gray-800 card mb-12">
<table class="min-w-full text-left text-sm">
<thead class="bg-gray-800/50 text-white border-b border-gray-800">
<tr>
<th class="px-6 py-4 font-bold">Variable</th>
<th class="px-6 py-4 font-bold">Description</th>
</tr>
</thead>
<tbody class="divide-y divide-gray-800 text-gray-400">
<tr>
<td class="px-6 py-4 text-white font-medium"><code>PINNER_NO_CACHE</code></td>
<td class="px-6 py-4">Set to <code>true</code> to disable persistent disk caching (caches are bypassed).</td>
</tr>
<tr>
<td class="px-6 py-4 text-white font-medium"><code>PINNER_CACHE_TTL</code></td>
<td class="px-6 py-4">Configure custom cache TTL duration in seconds.</td>
</tr>
<tr>
<td class="px-6 py-4 text-white font-medium"><code>PINNER_CONCURRENCY</code></td>
<td class="px-6 py-4">Override the number of concurrent API requests.</td>
</tr>
<tr>
<td class="px-6 py-4 text-white font-medium"><code>PINNER_IGNORE</code></td>
<td class="px-6 py-4">Override the list of ignored actions (comma-separated).</td>
</tr>
<tr>
<td class="px-6 py-4 text-white font-medium"><code>PINNER_GITHUB_URL</code></td>
<td class="px-6 py-4">Override default GitHub API URL. Also available for GitLab, Bitbucket, Forgejo, and CircleCI.</td>
</tr>
</tbody>
</table>
</div>
<h3 class="text-lg font-bold text-white mb-4">Cloud Provider Resolution</h3>
<div class="grid grid-cols-1 md:grid-cols-3 gap-6">
<div class="card p-6 rounded-xl">
<h4 class="text-white font-bold mb-2">AWS ECR</h4>
<p class="text-xs text-gray-400 leading-relaxed">
To resolve private OCI digests from AWS ECR, pass the login token:
</p>
<pre class="mt-4 text-[10px]"><code>PINNER_OCI_USERNAME=AWS \
PINNER_OCI_PASSWORD=$(aws ecr get-login-password) \
pinner pin</code></pre>
</div>
<div class="card p-6 rounded-xl">
<h4 class="text-white font-bold mb-2">Azure Marketplace</h4>
<p class="text-xs text-gray-400 leading-relaxed">
Tasks are automatically resolved to the <code>microsoft/azure-pipelines-tasks</code> monorepo to safely query and map release commit hashes.
</p>
</div>
<div class="card p-6 rounded-xl">
<h4 class="text-white font-bold mb-2">CircleCI Orbs</h4>
<p class="text-xs text-gray-400 leading-relaxed">
Pinner supports Docker images inside CircleCI configs. CircleCI Orbs use semantic version routing and are not hash-pinned.
</p>
</div>
</div>
</section>
<section class="mb-20" id="configuration-file">
<h2 class="text-2xl font-bold text-white mb-8 flex items-center">
<i class="fas fa-file-code text-sky-400 mr-4"></i> Configuration File
</h2>
<p class="text-gray-400 mb-8 leading-relaxed">
Create a <code>.pinner.toml</code> file in your repository root to persist settings and share security whitelists with your team.
</p>
<div class="card p-8 rounded-xl mb-12">
<h3 class="text-lg font-bold text-white mb-4">Example .pinner.toml</h3>
<pre class="text-sm"><code># Actions to exclude from processing
ignore = ["actions/checkout", "my-org/private-repo"]
# Execution and Caching settings
concurrency = 5
no_cache = false
cache_ttl = 3600 # Cache TTL in seconds
# API URL overrides (for Enterprise instances)
github_url = "https://github.mycompany.com/api/v3"
gitlab_url = "https://gitlab.mycompany.com/api/v4"
# Whitelist of vetted dependency hashes/references
vetted = [
# Plain string format
"actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332",
# Structured format with original tag and insertion timestamp
{ ref = "actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10", tag = "v6.0.3", timestamp = "2026-06-18T15:28:25Z" }
]
# Blacklist of compromised dependency hashes/references
compromised = [
"actions/checkout@badhash1234567890badhash1234567890bad",
{ ref = "actions/checkout@evilhash1234567890evilhash1234567890bad", tag = "v3.1.0", timestamp = "2026-06-18T15:28:25Z" }
]
# Disable visual security feedback (default: false)
no_security_feedback = false</code></pre>
</div>
<h3 class="text-lg font-bold text-white mb-4">Global Configuration Hierarchy</h3>
<p class="text-gray-400 mb-6 leading-relaxed">
Pinner automatically aggregates whitelists and blacklists from standard configuration paths. Locations checked (from lowest to highest precedence):
</p>
<ul class="list-disc pl-6 text-gray-400 mb-8 space-y-2 text-sm">
<li><code>~/.cache/pinner/config.toml</code> (Global caching)</li>
<li><code>~/.config/pinner/config.toml</code> (Global config)</li>
<li><code>~/.pinner.toml</code> (Home config)</li>
<li><code>.pinner.toml</code> (Local project config - overrides all global values)</li>
</ul>
<div class="bg-sky-500/5 p-4 rounded-xl border border-sky-500/20 text-xs text-gray-400 leading-relaxed">
<strong>Local Precedence Rules</strong>:
A project-level <code>.pinner.toml</code> serves as a strict override. If a dependency reference is marked <code>vetted</code> locally, it overrides global <code>compromised</code> flags, and if marked <code>compromised</code> locally, it overrides global <code>vetted</code> entries.
</div>
</section>
</main>
<pinner-footer></pinner-footer>
</body>
</html>
