# Configuring Action Inputs for Local Runs with act --input

> Configure action inputs for local runs with act--input. Pass values to ${{ inputs.* }} expressions using flags or files for seamless local GitHub Actions development.

- Repository: [nektos/act](https://github.com/nektos/act)
- Tags: how-to-guide
- Published: 2026-03-03

---

**Use the `--input key=value` flag or `--input-file` to pass values to `${{ inputs.* }}` expressions when running GitHub Actions locally with act.**

When testing GitHub Actions workflows locally using the open-source tool `act`, supplying values for action inputs requires specific CLI configuration. The `nektos/act` repository provides the `--input` and `--input-file` flags to inject these variables into your local runner environment, enabling full emulation of workflow inputs without pushing to GitHub.

## How the `--input` Flag Is Defined

The command-line interface declares the input flag in [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) at lines 78–82, where Cobra binds the flag to the `Input` struct:

```go
rootCmd.Flags().StringArrayVarP(&input.inputs, "input", "", []string{}, "action input to make available to actions (e.g. --input myinput=foo)")

```

The `Input` struct, defined in [`cmd/input.go`](https://github.com/nektos/act/blob/main/cmd/input.go) (lines 9–22), stores the raw values in a string slice:

```go
type Input struct {
    inputs []string
    // ... other fields
}

```

This struct also provides helper methods such as `Envfile()`, `Secretfile()`, `Varfile()`, and `Inputfile()` (lines 13–17) to resolve file-path flags relative to the working directory.

## Data Flow from CLI to Workflow

Understanding how `act` processes inputs helps debug configuration issues. The flow follows three distinct stages:

1. **Flag Parsing** – Cobra stores each `--input key=value` occurrence in `input.inputs` as a raw string.
2. **Resolution** – The `Input.resolve` method (lines 70–81 of [`cmd/input.go`](https://github.com/nektos/act/blob/main/cmd/input.go)) converts relative file paths to absolute ones. Note that this resolution applies only to file-path flags, not to the plain key/value pairs passed via `--input`.
3. **Runner Injection** – In [`pkg/runner/action.go`](https://github.com/nektos/act/blob/main/pkg/runner/action.go), the runner constructs a `github.ActionsInput` map by splitting each slice element on the `=` character. This map is injected into the action's environment, making values accessible via `${{ inputs.<name> }}`.

## Practical Usage Patterns

### Single and Multiple Inputs

Provide individual inputs using repeated `--input` flags:

```bash

# Single input

act -j build --input version=1.2.3

# Multiple inputs

act -j test --input env=staging --input debug=true --input region=eu-west-1

```

### File-Based Inputs with `--input-file`

For complex configurations, store inputs in a file and reference them with `--input-file`. The file must contain one `key=value` pair per line:

```bash
cat > .inputs <<'EOF'
version=1.2.3
debug=true
env=production
EOF

act -j deploy --input-file .inputs

```

**Important:** `act` does not automatically read an `.input` file; you must explicitly specify the file path using `--input-file`.

### Override Behavior

When combining `--input-file` with inline `--input` flags, command-line values take precedence. The runner processes the file first, then applies explicit CLI overrides:

```bash
act --input-file .inputs --input debug=false  # Overrides debug=true from file

```

## Accessing Inputs Inside Workflows

Once passed to `act`, inputs are available in workflow expressions using the standard GitHub Actions syntax. The runner injects these values before executing composite or Docker actions.

```yaml

# .github/workflows/example.yml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Display inputs
        run: |
          echo "Version: ${{ inputs.version }}"
          echo "Environment: ${{ inputs.env }}"

```

Running `act --input version=1.2.3 --input env=staging` will substitute these values into the workflow output.

## Key Implementation Files

The end-to-end input handling involves these critical source files:

- [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) – Declares the `--input` flag and binds it to the `Input.inputs` slice.
- [`cmd/input.go`](https://github.com/nektos/act/blob/main/cmd/input.go) – Defines the `Input` struct, path resolution logic, and file-handling helpers.
- [`pkg/runner/action.go`](https://github.com/nektos/act/blob/main/pkg/runner/action.go) – Parses the input slice into a `github.ActionsInput` map and injects it into the action environment.
- [`pkg/model/workflow.go`](https://github.com/nektos/act/blob/main/pkg/model/workflow.go) – Defines the workflow model that references inputs during expression evaluation.

## Summary

- The `--input` flag accepts `key=value` pairs to emulate GitHub Actions inputs locally.
- Flag definitions reside in [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) and state management in [`cmd/input.go`](https://github.com/nektos/act/blob/main/cmd/input.go).
- The runner converts inputs into a `github.ActionsInput` map in [`pkg/runner/action.go`](https://github.com/nektos/act/blob/main/pkg/runner/action.go).
- Use `--input-file` to load inputs from a line-delimited file; `act` does not auto-detect input files.
- Command-line inputs override values specified in input files.
- Access passed values in workflows via `${{ inputs.<name> }}` expressions.

## Frequently Asked Questions

### Does act automatically read `.input` files from the repository?

No. Unlike `.env` or `.secrets` files, `act` does not automatically detect or load input files. You must explicitly specify the file path using the `--input-file` flag. The file must contain one `key=value` pair per line, which the runner parses and merges with any `--input` flags provided on the command line.

### How do I override specific inputs when using an input file?

Command-line `--input` flags always take precedence over file-based inputs. The runner processes the `--input-file` first, then applies any `--input` flags, allowing you to override specific values without modifying the file. For example: `act --input-file .inputs --input debug=false` will use all values from `.inputs` except `debug`, which becomes `false`.

### Can I use act inputs with composite actions?

Yes. The `--input` flag works for both standard workflows and composite actions. In [`pkg/runner/action.go`](https://github.com/nektos/act/blob/main/pkg/runner/action.go), the runner builds the `github.ActionsInput` map and injects it into the environment before executing composite or Docker actions, making the values available via `${{ inputs.<name> }}` regardless of the action type.

### Where does act validate the input syntax?

`act` performs minimal validation at the CLI level. The [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) file defines the flag as a string array, accepting any `key=value` format. Actual parsing and splitting on the `=` character occur in [`pkg/runner/action.go`](https://github.com/nektos/act/blob/main/pkg/runner/action.go) when the runner constructs the `github.ActionsInput` map. Invalid formats may result in empty values rather than immediate errors.