/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 only previously cached results from ~/.topgun/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 manifest is still written to ~/.topgun/audit-manifest.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 is passed.topgun-tools clear-cache.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 topgun-tools set-token command to store a token:
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 tokens, cache, and pipeline state outside of Claude Code.
| Command | Description |
|---|---|
| set-token <registry> <token> | Store a registry auth token in the OS credential store |
| get-token <registry> | Retrieve and print a stored token (masked except last 4 chars) |
| delete-token <registry> | Remove a stored token from the credential store |
| clear-cache | Delete all files in ~/.topgun/cache/ |
| clear-cache --older-than <hours> | Delete cache files older than the specified number of hours |
| reset-state | Delete ~/.topgun/state.json — equivalent to --reset flag |
| show-manifest | Pretty-print the most recent audit-manifest.json |
| show-install-log | Print all entries from install-log.json in a readable table |
| list-registries | Print all configured registry adapters and their current status (enabled/disabled, auth present) |