CLI Reference

Complete reference for all CLI options and environment variables.

Authentication Recommended

When running locally, set a GITHUB_TOKEN environment variable to avoid rate limits. Without it, you're limited to 60 API requests per hour. 

export GITHUB_TOKEN=ghp_your_token_here

Options

All commands accept the following options:

-w, --workflows <path>

Path to the workflows directory.

Default: .github/workflows

node dist/cli.js generate --workflows ./my-workflows

-o, --output <path>

Path to the lockfile.

Default: .github/actions.lock.json

node dist/cli.js generate --output ./lockfile.json

-t, --token <token>

GitHub token for API authentication. Required for private repositories or to avoid rate limiting.

node dist/cli.js generate --token ghp_xxxxxxxxxxxx

Generate Options

--require-sha

Require all action references to be full 40-character commit SHAs. Fails if any workflow uses tags like @v4 instead of full SHAs.

node dist/cli.js generate --require-sha

Verify Options

--skip-sha

Skip SHA resolution verification. This makes verification faster but less secure.

node dist/cli.js verify --skip-sha

--skip-integrity

Skip integrity hash verification. This makes verification faster but less secure.

node dist/cli.js verify --skip-integrity

--skip-advisories

Skip checking locked actions against the GitHub Advisory Database for known vulnerabilities. Advisory checking is enabled by default.

# Disable advisory checking
node dist/cli.js verify --skip-advisories

-c, --comment / --no-comment

Post a PR comment when verification fails. Enabled by default.

# Disable PR comments
node dist/cli.js verify --no-comment

Environment Variables

GITHUB_TOKEN

Alternative to the --token option. If both are provided, the command-line option takes precedence.

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
node dist/cli.js generate

In GitHub Actions, this is automatically available:

- uses: gjtorikian/gh-actions-lockfile@v1
  with:
    mode: generate
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Running with Different Runtimes

The built CLI works with Node.js without additional dependencies:

node dist/cli.js <command> [options]

Development Mode

You can also run directly from source with tsx:

npx tsx src/index.ts <command> [options]

Examples

Generate a lockfile with custom paths:

node dist/cli.js generate \
  --workflows ./workflows \
  --output ./workflows/actions.lock.json

Verify in CI with explicit token:

GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} node dist/cli.js verify

List dependencies for a specific lockfile:

node dist/cli.js list --output ./custom-lockfile.json