--- sidebar_position: 1 description: Every gitea-runner command and flag, generated from the runner sources. --- # Command line reference {/* Generated by update_runner_docs.sh from the gitea/runner sources, do not edit. */} `gitea-runner` is a single binary with one subcommand per task. `--config` / `-c` is global: every command that reads configuration accepts it, and commands that do not read any ignore it. ## gitea-runner ```text Gitea Runner Usage: gitea-runner [command] Available Commands: bug-report Print information useful when filing a bug report cache-server Start a cache server for the cache action config Generate, read and edit config files daemon Run as a runner daemon exec Run workflow locally. help Help about any command register Register a runner to the server Flags: -c, --config config Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable -h, --help help for gitea-runner -v, --version version for gitea-runner Use "gitea-runner [command] --help" for more information about a command. ``` ## register Registers the runner against a Gitea instance and writes the registration file. Interactive unless `--no-interactive` is given; the token can also come from `--token-file` or the `GITEA_RUNNER_REGISTRATION_TOKEN` environment variable. See [Registering a runner](../registration.md). ```text Register a runner to the server Usage: gitea-runner register [flags] Flags: --ephemeral Configure the runner to be ephemeral and only ever be able to pick a single job (stricter than --once) -h, --help help for register --instance string Gitea instance address --labels string Runner tags, comma separated --name string Runner name --no-interactive Disable interactive mode --token string Runner token (or set the GITEA_RUNNER_REGISTRATION_TOKEN envvar) --token-file string Path to a file containing the runner token Global Flags: -c, --config config Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable ``` ## daemon Runs the runner: it polls the instance for jobs and executes them until it is stopped. `--labels` (default: `GITEA_RUNNER_LABELS`) overrides the labels of an already registered runner, and `--once` exits after a single job. ```text Run as a runner daemon Usage: gitea-runner daemon [flags] Flags: -h, --help help for daemon --labels string Runner labels, comma separated. Overrides the labels of an already registered runner --once Run one job then exit Global Flags: -c, --config config Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable ``` ## exec Runs a workflow from the current repository locally, without a Gitea instance and without the runner configuration file. Useful for debugging a workflow before pushing it. Runner YAML is not loaded, so hooks and cache settings do not apply. ```text Run workflow locally. Usage: gitea-runner exec [flags] Flags: --artifact-server-addr string Defines the address where the artifact server listens --artifact-server-path string Defines the path where the artifact server stores uploads and retrieves downloads from. If not specified the artifact server will not start. (default ".") --artifact-server-port string Defines the port where the artifact server listens (will only bind to localhost). (default "34567") --container-architecture string Architecture which should be used to run containers, e.g.: linux/amd64. If not specified, will use host default architecture. Requires Docker server API Version 1.41+. Ignored on earlier Docker server platforms. --container-cap-add stringArray kernel capabilities to add to the workflow containers (e.g. --container-cap-add SYS_PTRACE) --container-cap-drop stringArray kernel capabilities to remove from the workflow containers (e.g. --container-cap-drop SYS_PTRACE) --container-daemon-socket string Path to Docker daemon socket which will be mounted to containers (default "/var/run/docker.sock") --container-opts string container options -d, --debug enable debug log --default-actions-url string Defines the default url of action instance. (default "https://github.com") --detect-event Use first event type from workflow as event that triggered the workflow -C, --directory string working directory (default ".") -n, --dryrun dryrun mode --env stringArray env to make available to actions with optional value (e.g. --env myenv=foo or --env myenv) --env-file string environment file to read and use as env in the containers (default ".env") -E, --event string run a event name -e, --eventpath string path to a JSON event payload file exposed as the event that triggered the workflow --gitea-instance string Gitea instance to use. -h, --help help for exec -i, --image string Docker image to use. Use "-self-hosted" to run directly on the host. (default "docker.gitea.com/runner-images:ubuntu-latest") --insecure-secrets NOT RECOMMENDED! Doesn't hide secrets while printing logs. -j, --job string run a specific job ID; when several workflow files define that job, also pass --workflows/-W to select the file --json Output logs in json format -l, --list list workflows --network string Specify the network to which the container will connect --no-recurse Flag to disable running workflows from subdirectories of specified path in '--workflows'/'-W' flag --no-skip-checkout Do not skip actions/checkout --privileged use privileged mode -p, --pull pull docker image(s) even if already present --rebuild rebuild local action docker image(s) even if already present -s, --secret stringArray secret to make available to actions with optional value (e.g. -s mysecret=foo or -s mysecret) --tool-cache-mode string What to mount at RUNNER_TOOL_CACHE: none, or shared to reuse one tool cache across runs (default "none") --use-gitignore Controls whether paths specified in .gitignore should be copied into container (default true) --userns string user namespace to use --var stringArray variable to make available to actions with optional value (e.g. --var myvar=foo or --var myvar) -W, --workflows string path to workflow file(s) (default "./.gitea/workflows/") Global Flags: -c, --config config Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable ``` ## cache-server Runs only the cache server, so several runners can share one cache. `--dir`, `--host` and `--port` override the matching `cache.*` keys; every other setting, `cache.external_secret` included, has to come from the config file. See [Caching](../cache.md#sharing-a-cache-between-runners). ```text Start a cache server for the cache action Usage: gitea-runner cache-server [flags] Flags: -d, --dir string Cache directory -h, --help help for cache-server -s, --host string Host of the cache server -p, --port uint16 Port of the cache server Global Flags: -c, --config config Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable ``` ## generate-config Prints the commented example configuration on stdout, which is the starting point for a config file: `gitea-runner generate-config > config.yaml`. ```text Print the example config, which documents every option Usage: gitea-runner generate-config [flags] Flags: -h, --help help for generate-config Global Flags: -c, --config config Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable ``` ## bug-report Prints the runner version, Go version, OS/architecture and CPU count, for pasting into an issue. ```text Print information useful when filing a bug report Usage: gitea-runner bug-report [flags] Flags: -h, --help help for bug-report Global Flags: -c, --config config Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable ```