CircleCI: cd Into Directory

Ryan Kienstra on October 14, 2022

Here’s how to cd into a directory in CircleCI.

If No working_directory

If there’s no working_directory value in the step, you’ll start in the directory /home/circleci/project:

      - checkout
      - run:
          name: Running e2e tests
          command: |
            pwd
            # prints /home/circleci/project
            ls
            # prints the files in your repo: babel.config.json  LICENSE  php etc…Code language: YAML (yaml)

That directory will also have your repo, assuming your checkout command didn’t have a path value.

If the checkout command had a path value, it’ll be checked out there:

      - checkout:
          path: /tmp/e2e
      - run:
          name: Running e2e tests
          command: |
            pwd
            # prints /home/circleci/project
            cd /tmp/e2e
            ls
            # prints babel.config.json  LICENSE  php etc…Code language: YAML (yaml)

If working_directory

If there’s a working_directory value in the step, you’ll start in that directory, relative to /home/circleci/project

      - run:
          name: Running e2e tests
          working_directory: e2e
          command: |
            pwd
            # prints /home/circleci/project/e2e
Code language: YAML (yaml)

Because that doesn’t start with /, it is relative to ~/project/

So it’ll be ~/project/e2e

If it started with / or ~/ it’d be an absolute path:

      - run:
          name: Running e2e tests
          working_directory: /tmp/e2e
          command: |
            pwd
            # prints /tmp/e2e
Code language: YAML (yaml)

Don’t Do This

      - run: cd foo
      - run: npm testCode language: YAML (yaml)

Each run command goes back to /home/circleci/project or its working_directory:

  - run: cd foo && pwd # prints /home/circleci/project/foo
  - run: pwd # prints /home/circleci/projectCode language: YAML (yaml)

Checking Out Repo To Another Directory

version: 2.1

references:
  REPO_PATH: &REPO_PATH
    /tmp/e2e

jobs:
  js-build:
    docker:
      - image: cimg/node:14.18
    steps:
      - checkout:
          path: *REPO_PATH
      - run:
          working_directory: *REPO_PATH
          command: |
            pwd
            # prints /tmp/e2e
      - run:
          working_directory: *REPO_PATH
          command: npm test
Code language: YAML (yaml)

But you’ll only need REPO_PATH if you have multiple steps.

Usually, you can simply pass a string literal to working_directory.

And this should only be needed if you’re checking out multiple repos.

Like a repo for e2e tests, and a repo for your project.

Instant Feedback

Here’s how to cd into directory and see where you are, right away.

In VS Code, install the extension Local CI.

1. Click its icon on the left

2. Click ‘Select Repo’

3. Select the repo

4. You’ll see the jobs:

5. Click the job you want bash access to

6. Click ‘debugging’

7. Run bash commands, like cd into directory:

$ whoami
circleci
$ pwd
/home/circleci
$ ls
project
$ cd project
$ ls
babel.config.json  package-lock.json
composer.json      php
composer.lock      README.md
LICENSE            src
node_modules       tests
package.jsonCode language: Bash (bash)

Most of the time, you shouldn’t need to cd in CircleCI commands.

working_directory should get you into the right directory.

But if you need to change directories, do it in the same command.

Local CI can help get instant feedback on where you are.

But if you’d prefer to use the CircleCI CLI on your own…

Here’s how to do that.