{"id":13692062,"url":"https://github.com/dependabot/cli","last_synced_at":"2026-01-06T20:31:27.769Z","repository":{"id":60520781,"uuid":"540522997","full_name":"dependabot/cli","owner":"dependabot","description":"A tool for testing and debugging Dependabot update jobs.","archived":false,"fork":false,"pushed_at":"2025-05-06T19:35:26.000Z","size":677,"stargazers_count":300,"open_issues_count":23,"forks_count":42,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-05-06T20:35:35.075Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dependabot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-09-23T16:16:10.000Z","updated_at":"2025-05-06T19:35:28.000Z","dependencies_parsed_at":"2023-11-13T20:25:17.941Z","dependency_job_id":"b2aaa204-0b13-4077-a4f1-e69558579f26","html_url":"https://github.com/dependabot/cli","commit_stats":{"total_commits":237,"total_committers":22,"mean_commits":"10.772727272727273","dds":0.6244725738396624,"last_synced_commit":"4e7612fe884683ade8c54ad8fd137fc6da92bb84"},"previous_names":[],"tags_count":79,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dependabot%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dependabot%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dependabot%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dependabot%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dependabot","download_url":"https://codeload.github.com/dependabot/cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384988,"owners_count":22062422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T17:00:53.187Z","updated_at":"2026-01-06T20:31:27.763Z","avatar_url":"https://github.com/dependabot.png","language":"Go","funding_links":[],"categories":["Go","Uncategorized"],"sub_categories":["Uncategorized"],"readme":"\u003ch1 align=\"center\"\u003e\n    \u003cpicture\u003e\n        \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://user-images.githubusercontent.com/7659/174594540-5e29e523-396a-465b-9a6e-6cab5b15a568.svg\"\u003e\n        \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://user-images.githubusercontent.com/7659/174594559-0b3ddaa7-e75b-4f10-9dee-b51431a9fd4c.svg\"\u003e\n        \u003cimg src=\"https://user-images.githubusercontent.com/7659/174594540-5e29e523-396a-465b-9a6e-6cab5b15a568.svg\" alt=\"Dependabot\" width=\"336\"\u003e\n    \u003c/picture\u003e\n\u003c/h1\u003e\n\nThe `dependabot` CLI is a tool for running Dependabot update jobs.\n\n## Installation\n\nUse any of the following for a pain-free installation:\n\n* If you have [`go`](https://go.dev/doc/install) installed, you can run:\n   ```shell\n   go install github.com/dependabot/cli/cmd/dependabot@latest\n   ```\n   The benefit of this method is that re-running the command will always update to the latest version.\n* You can download a pre-built binary from the [releases] page.\n* On Mac, you can run `brew install dependabot`\n\n## Requirements\n\n* [Docker]\n\n## Contributing\n\nCheck out our [contributing guidelines][contributing] for instructions on\nbuilding the project locally, sharing feedback, and submitting pull requests.\n\n## Usage\n\n```console\n$ dependabot\nRun Dependabot jobs from the command line.\n\nUsage:\n  dependabot [command]\n\nExamples:\n  $ dependabot update go_modules dependabot/cli\n  $ dependabot test -f input.yml\n\nAvailable Commands:\n  completion  Generate the autocompletion script for the specified shell\n  help        Help about any command\n  test        Run a smoke test\n  update      Perform an update job\n\nFlags:\n  -h, --help                   help for dependabot\n      --proxy-image string     container image to use for the proxy (default \"ghcr.io/github/dependabot-update-job-proxy/dependabot-update-job-proxy:latest\")\n      --updater-image string   container image to use for the updater\n  -v, --version                version for dependabot\n\nUse \"dependabot [command] --help\" for more information about a command.\n```\n\n### `dependabot update`\n\nRun the `update` subcommand to run a Dependabot update job for the provided ecosystem and repo.\nThis does not create PRs, but outputs data that could be used to create PRs. For an example of how to do that see\nthe [example CLI usage](https://github.com/dependabot/example-cli-usage) repo.\n\n```console\n$ dependabot update go_modules dependabot/cli\n# ...\n+----------------------------------------------------+\n|        Changes to Dependabot Pull Requests         |\n+---------+------------------------------------------+\n| created | rsc.io/quote/v3 ( from 3.0.0 to 3.1.0 )  |\n| created | rsc.io/sampler ( from 1.3.0 to 1.99.99 ) |\n+---------+------------------------------------------+\n```\n\nThe first argument specifies the _package manager_\n(e.g. `go_modules`, `bundler`, `npm_and_yarn`, or `pip`).\nAvailable values are defined in [`dependabot-core`](https://github.com/dependabot/dependabot-core/blob/main/common/lib/dependabot/config/file.rb);\nby convention, each ecosystem registers itself according to\n[the name of its top-level subdirectory][dependabot-omnibus] in the repo.\n\nThe second argument is the _repository_ name with owner\n(e.g. `dependabot/cli` for this repo).\n\nBy default, repositories are fetched from GitHub.com.\nTo override this, set the `--provider` / `-p` option to\n`azure`, `bitbucket`, `codecommit`, or `gitlab`.\n\nTo update dependencies in a subdirectory,\nspecify a path with the `--directory` / `-d` option.\n\nSet the `LOCAL_GITHUB_ACCESS_TOKEN` environment variable\nto a [Personal Access Token (PAT)][PAT],\nand the CLI will pass that token to the proxy\nto authenticate API requests to GitHub\n(for example, to access private repositories or packages).\n\n### Job description file\n\nThe command-line interface for the `update` subcommand\nprovides only a subset of the available options for a Dependabot update job.\nTo perform security updates or authenticate against a private registry,\nyou can pass a job description to the `update` subcommand\nusing the `--file` / `-f` option\n(this replaces the package manager and repository name arguments).\n\n```console\ndependabot update -f job.yaml\n```\n\n```yaml\n# job.yaml\njob:\n    package-manager: npm_and_yarn\n    allowed-updates:\n      - update-type: all\n    dependencies: # required arg when `security-updates-only: true` set\n      - 'express'\n    security-advisories:\n      - dependency-name: express\n        affected-versions:\n          - \u003c5.0.0\n        patched-versions: []\n        unaffected-versions: []\n    security-updates-only: true\n    source:\n        provider: github\n        repo: dependabot/smoke-tests\n        directory: /\n        commit: 66115359e6f6cc3af6a661c5d5ae803720b98cb8\ncredentials:\n  - type: npm_registry\n    registry: https://npm.pkg.github.com\n    token: $LOCAL_GITHUB_ACCESS_TOKEN\n```\n\nThis example describes an update job\nresponsive to a hypothetical security advisory affecting\n`express` package releases earlier than version `5.0.0`.\nWhen performing this job,\nDependabot will consult the private registry specified\nusing the provided credentials\ninstead of the default NPM registry.\n\nBefore running an update job,\nthe `dependabot` CLI replaces any `$`-prefixed values in the YAML file\nwith values from the environment.\n(e.g. `$LOCAL_GITHUB_ACCESS_TOKEN`).\n\n\u003e **Note**\n\u003e\n\u003e The job description file format isn't documented formally yet,\n\u003e but you can find examples in the [smoke tests](https://github.com/dependabot/smoke-tests/tree/main/tests)\n\u003e and look at the [model directory](/internal/model) for how the CLI models the job. \n\n### How it works\n\nWhen you run the `update` subcommand,\nthe CLI does the following:\n\n1. Pulls the [updater] and [proxy] images from the container registry\n2. Creates and configures [container networks]\n   so the updater communicates exclusively through the proxy\n3. Starts the proxy\n4. Starts the updater, using the job description as input\n5. Records calls made by the updater to create and manage pull requests\n6. Writes recorded calls as YAML (if `--output` / `-o` option is specified)\n\n```mermaid\nsequenceDiagram\n    CLI-\u003e\u003eProxy: Starts the proxy\n    CLI-\u003e\u003eUpdater: Starts the updater\n    Updater-\u003e\u003eGitHub: Fetches repo\n    loop\n    Updater-\u003e\u003eRegistry: Fetches package information\n    Updater-\u003e\u003eCLI: Records calls to create or updates PRs\n    end\n    CLI-\u003e\u003eYAML file: Writes recorded calls to output file (if specified)\n```\n\nAll network requests made by the updater go through the proxy.\nThe proxy injects credentials into outbound requests\nso that the updater doesn't have access to secrets.\nThis isolation is especially important for\npackage managers that run untrusted code during an update job,\nsuch as when evaluating manifest files or executing install scripts.\n\n### `dependabot test`\n\nRun the `test` subcommand\nwith a smoke test file specified by the `--file` / `-f` option\nto test the expected behavior for a Dependabot update job.\n\n```console\n$ dependabot test -f smoke-test.yaml\n# ...\n+------------------------------------------+\n|   Changes to Dependabot Pull Requests    |\n+---------+--------------------------------+\n| created | ubuntu ( from 17.04 to 22.04 ) |\n+---------+--------------------------------+\n\ntime=\"2022-09-28T08:15:26Z\" level=info msg=\"15/15 calls cached (100%)\"\n```\n\n### Smoke test\n\nA smoke test describes the input _and_ expected output of a Dependabot job.\n\n```yaml\n# smoke-test.yaml\ninput:\n    job:\n        package-manager: docker\n        allowed-updates:\n          - update-type: all\n        ignore-conditions:\n          - dependency-name: ubuntu\n            source: tests/smoke-docker.yaml\n            version-requirement: '\u003e22.04'\n        source:\n            provider: github\n            repo: dependabot/smoke-tests\n            directory: /\n            commit: 832e37c1a7a4ef89feb9dc7cfa06f62205191994\noutput:\n  - type: create_pull_request\n    expect:\n        data:\n            base-commit-sha: 832e37c1a7a4ef89feb9dc7cfa06f62205191994\n            dependencies:\n              - name: ubuntu\n                previous-requirements:\n                  - file: Dockerfile\n                    groups: []\n                    requirement: null\n                    source:\n                        tag: \"17.04\"\n                previous-version: \"17.04\"\n                requirements:\n                  - file: Dockerfile\n                    groups: []\n                    requirement: null\n                    source:\n                        tag: \"22.04\"\n                version: \"22.04\"\n```\n\nThis example smoke test describes the expected behavior for Dependabot\nto update the base image of a Dockerfile from `ubuntu:17.04` to `ubuntu:22.04`.\n\n* The `input` field consists of a `job` and any `credentials`.\n  (this is equivalent a [job description file](#job-description-file)).\n* The `output` field comprises an array of expectation objects.\n  These correspond to requests made by the updater to the Dependabot API service\n  when performing an update job.\n\n\u003e **Note**\n\u003e\n\u003e The smoke test format isn't documented publicly,\n\u003e but you can find examples in the [`smoke-tests` repo][smoke-tests]\n\u003e and check [the `Job` class in `dependabot-core`][dependabot-updater-job].\n\n### Producing a test\n\nTo produce a smoke test that tests Dependabot behavior for a given repo,\nrun the `update` subcommand and set the `--output` / `-o` option to a file path.\n\n```console\ndependabot update go_modules dependabot/cli -o go-smoke-test.yml\n```\n\nRun the `test` subcommand for the generated smoke test,\nspecifying a cache directory with the `--cache` option.\n\n```console\ndependabot test -f go-smoke-test.yml --cache ./tmp/cache\n```\n\nWhile performing the update job,\nthe CLI writes cached responses to requests in the specified directory.\n\nRun the above command a second time,\nand you should see a line that looks like this at the bottom of the output:\n\n\u003e time=\"2022-09-28T08:14:01Z\" level=info msg=\"117/117 calls cached (100%)\"\n\nWhen the cache coverage for a smoke test is 100%,\nsubsequent runs of the `test` subcommand\nare most likely to be fast and deterministic.\nAny cache misses indicate an external request made by the updater,\nwhich may cause tests to fail unexpectedly\n(for example, when a new version of a package is released).\n\n## Debugging with the CLI\n\nSee the [debugging doc](/docs/debugging.md) for details.\n\n\n## Troubleshooting\n\n### \"Docker daemon not running\"\n\n```\nfailed to pull ghcr.io/github/dependabot-update-job-proxy/dependabot-update-job-proxy:latest:\nError response from daemon: dial unix docker.raw.sock: connect: no such file or directory\n```\n\nThe CLI requires Docker to be running on your machine.\nFollow the instructions on [Docker's website][Docker]\nto get the latest version of Docker installed and running.\n\nYou can verify that Docker is running locally with the following command:\n\n```console\ndocker --version\n```\n\n### \"Network internet is ambiguous\"\n\n```\nfailed to start container: Error response from daemon: network internet is ambiguous (2 matches found on name)\n```\n\nThis error can occur when the CLI exits before having an opportunity to clean up\n(e.g. terminating with \u003ckbd\u003e^\u003c/kbd\u003e\u003ckbd\u003eC\u003c/kbd\u003e).\nRun the following command to remove all unused networks:\n\n```console\ndocker network prune\n```\n\n### \"POST http://host.docker.internal:(port)/update_jobs/cli/update_dependency_list: No response from server\"\n\nWhen locally running the CLI, if you do not set the `--api-url` argument, the default is\nto connect to `host.docker.internal` which is effectively a \"loopback\" endpoint that just\nlogs the commands set to it. The default IP address used for sending these requests is\n`0.0.0.0` which normally works in Linux.\n\nHowever, when running under WSL2, for some (currently unknown) reason, the `0.0.0.0` default\nsetting does not work. The workaround is to add this to your CLI environment:\n\n`export FAKE_API_HOST=127.0.0.1`\n\nThis allows the requests to go through on WSL2.\n\nSecurity-wise, it would actually be better if *this* was the default. For more background on\nthe issue, see \u003chttps://github.com/dependabot/cli/issues/113#issuecomment-1610129508\u003e\n\n[Docker]: https://docs.docker.com/get-started/\n[contributing]: ./.github/CONTRIBUTING.md\n[updater]: https://github.com/dependabot/dependabot-core/pkgs/container/dependabot-updater\n[proxy]: https://github.com/orgs/github/packages/container/package/dependabot-update-job-proxy%2Fdependabot-update-job-proxy\n[gh]: https://github.com/cli/cli\n[releases]: https://github.com/dependabot/cli/releases\n[dependabot-core]: https://github.com/dependabot/dependabot-core\n[dependabot-omnibus]: https://github.com/dependabot/dependabot-core/blob/main/omnibus/lib/dependabot/omnibus.rb\n[container networks]: https://docs.docker.com/config/containers/container-networking/\n[smoke-tests]: https://github.com/dependabot/smoke-tests/tree/main/tests\n[dependabot-updater-job]: https://github.com/dependabot/dependabot-core/blob/main/updater/lib/dependabot/job.rb\n[PAT]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token\n\n### `ensure_equivalent_gemfile_and_lockfile` error\n\nThis error occurs when using `script/dependabot` and the Updater image is not in sync with dependabot-core. It can be resolved by rebuilding the Updater image.\n\nFor example, to rebuild the Updater image of the Go ecosystem, run this in the dependabot-core repository:\n``` console\n$ script/build go_modules\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdependabot%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdependabot%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdependabot%2Fcli/lists"}