You can use the command line tools to run Docker pipelines locally, on your laptop or personal computer, for development and debugging purposes. This is our answer to the common complaint that it works fine on my computer.

Installation

Install the command line tools on macOS using Homebrew:
```
brew install drone-cli
```
Install the command line tools on Windows using Scoop:
```
scoop install drone
```

Usage

The command line runner requires a working Docker installation. Drone executes your pipeline locally on your host machine using your local Docker daemon. Local execution does not have any communication with the Drone server.

Navigate to the root directory of your git repository where your .drone.yml file is located. Here is a basic configuration you can use for testing purposes:
```
kind: pipeline
type: docker
name: default

steps:
- name: test
  image: alpine
  commands:
  - echo hello
  - echo world
```
Execute your pipeline from the command line:
```
drone exec
```
The command streams the pipeline logs to your terminal for analysis. The command returns a non-zero exit code if the pipeline fails.
```
$ drone exec
[test:1] + echo hello
[test:2] hello
[test:3] + echo world
[test:4] world
```

Workspace

The command line runner mounts your current working directory, using docker volumes, as the working directory of your pipeline steps. This exposes your code to your pipeline. The clone step is therefore skipped when running locally.

Run Specific Pipelines

The command line runner runs the default pipeline. If you use a different name for you pipeline, or you define multiple pipelines in your yaml, you can execute a named pipeline using the --pipeline flag.

Example configuration with a pipeline named test

kind: pipeline
type: docker
name: test

steps:
- name: dist
  image: node
  commands:
  - npm install
  - npm run dist

Example command executes the test pipeline
```
drone exec --pipeline=test
```

Run Specific Steps

When running pipelines locally you can limit which pipeline steps are executed and which pipeline steps are skipped.

Execute only pipeline steps build and test

drone exec --include=build --include=test

Execute all pipeline steps except deploy
```
drone exec --exclude=deploy
```

Emulate Secrets

The command line runner does not have read access to secrets stored in your server. You can provide secrets to your local pipeline by passing secrets to the command line runner via text file.

Example pipeline that requires username and password environment variables, sourced from secrets.

kind: pipeline
type: docker
name: default

steps:
- name: test
  environment:
    USERNAME:
      from_secret: USERNAME
    PASSWORD:
      from_secret: PASSWORD

Create a simple text file with secrets defined one per line in key value format. For the purposes of this demo we name the file secrets.txt.
```
USERNAME=root
PASSWORD=password
```
Provide your secrets file via command line flags when executing your pipeline.
```
drone exec --secret-file=secrets.txt
```

The command line runner uses the dotenv package to read and parse the secrets file. If you are having problems with the secrets file please consult the official package documentation.

Emulate Metadata

The command line runner does not communicate with the Drone server and therefore do not have access to repository, commit and build metadata that are otherwise available to your pipeline.

You can emulate repository metadata by passing repository and build information to the command line runner using command line flags and environment variables.

Example command sets the branch:
```
drone exec --branch=master
```
Example command sets the build event:
```
drone exec --event=pull_request
```
Example command set metadata using environment variables:
```
DRONE_SYSTEM_HOST=drone.company.com drone exec
```

Trusted Mode

If your pipeline uses configurations that require trusted mode, you can enable trusted mode locally using the --trusted flag. Trusted mode grants a pipeline elevated privileges to your host machine. Please use with caution.

Example command enables trusted mode:
```
drone exec --trusted
```

Local vs Remote

The command line runner makes reasonable effort to emulate the server environment, however, there are notable differences that can impact execution:

The server clones your repository, while the command line runner mounts your current working directory. Any files or dependencies that already exist in your working directory are mounted into your pipeline as well.
The server has access to more data (commit details, repository details, etc). This data needs to be provided to the command line runner to more closely emulate the server environment.
The server has access to your oauth credentials and uses these credentials to generate a netrc file. These credentials need to be provided to the command line runner to more closely emulate the server environment.
The server has access to repository, organization and encrypted secrets. The command line runner does not have access to secrets or decryption keys stored in the server environment.