# Run builds on CircleCI using a local config file **URL:** \ **Category:** Tips, Tricks, and Hacks\ **Tags:** tips\ **Created:** [October 13, 2017, 1:06pm UTC](https://discuss.circleci.com/t/run-builds-on-circleci-using-a-local-config-file/17355 "2017-10-13T13:06:46Z")\ **Posts on this page:** 10\ **Page:** 1
**Author:** ![fernfernfern](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/fernfernfern/32/8596_2.png) [@fernfernfern](https://discuss.circleci.com/u/fernfernfern)\ **Post date:** [October 13, 2017, 1:06pm UTC](https://discuss.circleci.com/t/run-builds-on-circleci-using-a-local-config-file/17355/1 "2017-10-13T13:06:46Z")
Have you ever wanted to try out new changes to your CI configuration without the tedium of pushing new commits and polluting your git history? Here’s a simple technique you can use with CircleCI to quickly try out new iterations of your configuration file. Kicking off builds from your command line using a temporary config file that you can quickly update, test, and iterate. This will keep your git history cleaner, and help you test your CircleCI config faster. We’ll be using `curl` to instruct the CircleCI API to kick off a new build using a config file that we provide to it. The command looks like: ```auto curl --user ${CIRCLE_TOKEN}: \ --request POST \ --form revision=fa6a8ab9992345e16bbe0515dfb3b56f16f7ce55 \ --form config=@config.yml \ --form notify=false \ https://circleci.com/api/v1.1/project/github/fernfernfern/circleciapp/tree/master ``` Four important pieces to making this command work. - You need an API key from your CircleCI account. You can create an API token for your account by [clicking here](https://circleci.com/account/api). If you want to keep this command saved in a script it’s safest to export your API key to an environment variable `export CIRCLE_TOKEN=`, instead of saving it in the script. - A git commit hash from your repo that CircleCI can find and pull the code from. You can get this from `git log` if your local repository has the latest remote changes. - A local file in the same working directory as where you’re running the command, with a valid CircleCI configuration in that file. - The API URL with the correct username/organization, project name, and branch to run the build under. If successful when you run this command you’ll get a json response back containing some information about the new build, such as its build number. Here’s a video tutorial with more details to help you get started: ---
**Author:** ![levlaz](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/levlaz/32/36978_2.png) [@levlaz](https://discuss.circleci.com/u/levlaz)\ **Post date:** [October 13, 2017, 1:49pm UTC](https://discuss.circleci.com/t/run-builds-on-circleci-using-a-local-config-file/17355/2 "2017-10-13T13:49:25Z")
This should definitely also be a blog post 🙂 ---
**Author:** ![samandmoore](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/samandmoore/32/16927_2.png) [@samandmoore](https://discuss.circleci.com/u/samandmoore)\ **Post date:** [October 17, 2017, 3:02pm UTC](https://discuss.circleci.com/t/run-builds-on-circleci-using-a-local-config-file/17355/3 "2017-10-17T15:02:32Z")
Hi @fernfernfern, Thanks for sharing this. I had no idea that we could ship over the config in the POST request. That is super useful. Is it possible for that config to include workflows? I.e. will this solution work for CircleCI 2.0 workflows? Oh, I guess i’m also curious if this way of triggering builds respects all the other features of the platform, e.g. do github status messages get posted on the commit? Thanks again for sharing. ---
**Author:** ![fernfernfern](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/fernfernfern/32/8596_2.png) [@fernfernfern](https://discuss.circleci.com/u/fernfernfern)\ **Post date:** [October 18, 2017, 8:49am UTC](https://discuss.circleci.com/t/run-builds-on-circleci-using-a-local-config-file/17355/4 "2017-10-18T08:49:46Z")
We don’t have an API to trigger workflows yet, so this won’t work for workflows. Since this totally bypasses Github a lot of our functionality based off their webhooks will be missing. You should only see commit status messages for the builds that were triggered by pushing a commit. ---
**Author:** ![jvlobo](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/jvlobo/32/18545_2.png) [@jvlobo](https://discuss.circleci.com/u/jvlobo)\ **Post date:** [June 16, 2018, 9:19am UTC](https://discuss.circleci.com/t/run-builds-on-circleci-using-a-local-config-file/17355/5 "2018-06-16T09:19:15Z")
Nothing about testing workflows yet? Cheers. ---
**Author:** ![halfer](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/halfer/32/9083_2.png) [@halfer](https://discuss.circleci.com/u/halfer)\ **Post date:** [June 16, 2018, 10:53am UTC](https://discuss.circleci.com/t/run-builds-on-circleci-using-a-local-config-file/17355/6 "2018-06-16T10:53:00Z")
> [@jvlobo](#): > > Nothing about testing workflows yet? I don’t think the API supports that yet. You can see the [supported API calls here](https://circleci.com/docs/api/v1-reference/). ---
**Author:** ![philicious](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/philicious/32/12984_2.png) [@philicious](https://discuss.circleci.com/u/philicious)\ **Post date:** [July 12, 2018, 3:22pm UTC](https://discuss.circleci.com/t/run-builds-on-circleci-using-a-local-config-file/17355/7 "2018-07-12T15:22:47Z")
@fernfernfern I’ve used the API with a local config.yml alot in the past days for developing a new pipeline setup and testing individual jobs w/o triggering workflows. was working quite well so far. however, I now face a weird problem: The local config.yml doesnt seem to be used anymore but the one thats in the git repo I checkout. No matter what I change in the local config.yml, the API calls response JSON shows me the config in `circle_yml` key with the content of whats in git. so I cannot test anymore w/o doing commits all the time. any idea whats happening here? ---
**Author:** ![philicious](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/philicious/32/12984_2.png) [@philicious](https://discuss.circleci.com/u/philicious)\ **Post date:** [July 12, 2018, 3:41pm UTC](https://discuss.circleci.com/t/run-builds-on-circleci-using-a-local-config-file/17355/8 "2018-07-12T15:41:25Z")
A classic, shortly after posting coz you spent some time trying, you find the answer: it was a invalid config.yml discovered by running the Circle CLIs validate command on it [https://circleci.com/docs/2.0/local-cli/](https://circleci.com/docs/2.0/local-cli/) @nico it would really help if Circle would error out when posting a local config.yml thats invalid instead of silently picking the one thats in repo !! (feature request) ---
**Author:** ![fernfernfern](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/fernfernfern/32/8596_2.png) [@fernfernfern](https://discuss.circleci.com/u/fernfernfern)\ **Post date:** [October 10, 2018, 3:41pm UTC](https://discuss.circleci.com/t/run-builds-on-circleci-using-a-local-config-file/17355/9 "2018-10-10T15:41:27Z")
Closed on October 10, 2018, 3:41pm UTC This topic was automatically closed 90 days after the last reply. New replies are no longer allowed. ---
**Author:** ![Benny](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/benny/32/31553_2.png) [@Benny](https://discuss.circleci.com/u/Benny)\ **Post date:** [January 3, 2024, 1:47pm UTC](https://discuss.circleci.com/t/run-builds-on-circleci-using-a-local-config-file/17355/10 "2024-01-03T13:47:27Z")
Hello! Reviving this post to share that we’ve introduced a much easier way to run pipelines (yes, entire pipelines, not only individual jobs) based on your local config file. Full details here: > [@Announcing a new way to test run your local config from VS Code (Closed Preview)](https://discuss.circleci.com/t/announcing-a-new-way-to-test-run-your-local-config-from-vs-code-closed-preview/50046): > > We’re very excited to introduce a new way of triggering pipelines from our [VS Code extension](https://marketplace.visualstudio.com/items?itemName=circleci.circleci). From [version 2.0](https://marketplace.visualstudio.com/items/circleci.circleci/changelog), our new Run Panel lets you trigger pipelines from VS Code based on your local, unversioned config.yml file, rather than the one versioned on your branch. Triggering pipelines from VS Code lets you to iterate on your CircleCI config without committing your trial and error changes to your version control system. Test out your config changes, and only commit them when you are happy with…