/topgun Flags
All flags are optional. TopGun works with zero flags for most use cases.
Restrict the FindSkills search to a comma-separated list of registry names. By default, all enabled adapters run. Use this to target specific sources or speed up searches when you know where the skill lives.
Skip all live registry queries. TopGun uses the previously written found-skills-<hash>.json artifact for the current query and any matching entries in ~/.topgun/audit-cache/. Useful when working without internet access or when you want to re-run a pipeline on already-fetched candidates without hitting rate limits.
Discard any saved pipeline state (~/.topgun/state.json) and start the pipeline from scratch. Without this flag, an interrupted pipeline will resume from its last completed stage.
Bypass the audit cache and always run fresh SENTINEL passes, even if a clean result for this contentSha was cached within the last 24 hours. Use this when you want to re-audit a skill after the SENTINEL ruleset has been updated.
Skip the manual approval gate and automatically install the winning skill after a successful 2-pass SENTINEL audit. The full audit record is still written to ~/.topgun/audit-<hash>.json for review after the fact. Use with care in automated workflows.
Output Files
TopGun writes all pipeline artifacts to ~/.topgun/. These files are useful for debugging, audit trails, and pipeline resume.
--reset clears the active run before a fresh pipeline starts.validate-partials.sh.cache-lookup, cache-write, and cache-invalidate.Auth Token Storage
TopGun stores registry auth tokens in the macOS Keychain (or the OS credential store on Linux/Windows). Tokens are never written to disk in plaintext.
Configuring tokens
Use the bundled keychain helpers to store a token. The default account name is topgun, so the short two-argument form is usually enough:
Token usage by registry
- GitHub — increases rate limit from 60 to 5,000 requests/hour. Required if you search GitHub topics frequently.
- Smithery — unlocks private skill listings. Not required for public skills.
- GitLab — required only for private group or project repositories. Public GitLab repos work without a token.
topgun-tools.cjs
topgun-tools.cjs is a CLI utility bundled with TopGun for managing keychain tokens, cached audits, hooks, and pipeline state outside the main /topgun flow.
| Command | Description |
|---|---|
| init | Create the ~/.topgun/ directory tree, state file, and install registry if they do not already exist |
| state-read | Print the current state.json document |
| state-write <key> <value> | Update a single field in state.json |
| sha256 <text> | Return the SHA-256 hash for a string payload |
| cache-lookup <sha> | Read an audit-cache entry, including stale or ETag metadata when present |
| cache-write <sha> <json> | Write a JSON payload into ~/.topgun/audit-cache/ |
| cache-invalidate <sha> | --all | Delete one cached audit entry or clear the entire audit cache |
| lock-write <json> | Write the reproducibility lock at ~/.topgun/topgun-lock.json |
| lock-read | Print the current reproducibility lock |
| keychain-get <service> [account] | Read a stored token from the OS credential store |
| keychain-set <service> [account] <password> | Store or replace a token in the OS credential store |
| schemas [schema] | Print the built-in JSON schema definitions used by the pipeline artifacts |
| validate-partials --hash <hash> [--expected <N>] | Check that all expected per-registry partial files exist for a FindSkills run |