{"id":14066867,"url":"https://github.com/analythium/rconfig","last_synced_at":"2025-10-22T05:50:11.100Z","repository":{"id":43301854,"uuid":"455017836","full_name":"analythium/rconfig","owner":"analythium","description":"Manage R Configuration at the Command Line","archived":false,"fork":false,"pushed_at":"2025-07-04T05:07:33.000Z","size":4964,"stargazers_count":27,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-22T05:49:45.704Z","etag":null,"topics":["cli","config","json","r","rstats","yaml"],"latest_commit_sha":null,"homepage":"https://hub.analythium.io/rconfig/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/analythium.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-02-03T03:30:52.000Z","updated_at":"2025-10-06T09:38:11.000Z","dependencies_parsed_at":"2024-08-13T07:11:39.654Z","dependency_job_id":"cf07af4e-5e48-43de-aa59-50f525d90d31","html_url":"https://github.com/analythium/rconfig","commit_stats":{"total_commits":139,"total_committers":2,"mean_commits":69.5,"dds":"0.014388489208633115","last_synced_commit":"50864c5d4c9cdb4d901958533bba91b593f80981"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/analythium/rconfig","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/analythium%2Frconfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/analythium%2Frconfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/analythium%2Frconfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/analythium%2Frconfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/analythium","download_url":"https://codeload.github.com/analythium/rconfig/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/analythium%2Frconfig/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280389295,"owners_count":26322507,"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","status":"online","status_checked_at":"2025-10-22T02:00:06.515Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cli","config","json","r","rstats","yaml"],"created_at":"2024-08-13T07:05:18.375Z","updated_at":"2025-10-22T05:50:11.053Z","avatar_url":"https://github.com/analythium.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput:\n  md_document:\n    variant: gfm\n---\n\n```{r, echo = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\",\n  fig.path = \"README-\"\n)\nset.seed(0)\nknitr::opts_knit$set(root.dir = 'inst/examples')\n```\n\n# rconfig\n\n\u003e Manage R Configuration at the Command Line\n\n[![Build status](https://github.com/analythium/rconfig/actions/workflows/check.yml/badge.svg)](https://github.com/analythium/rconfig/actions)\n[![CRAN version](https://www.r-pkg.org/badges/version/rconfig)](https://CRAN.R-project.org/package=rconfig)\n[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/grand-total/rconfig)](https://hub.analythium.io/rconfig/)\n\nManage R configuration using files (YAML, JSON, INI, TXT)\nJSON strings and command line arguments. Command line arguments\ncan be used to override configuration. Period-separated command line\nflags are parsed as hierarchical lists. Environment variables, R global variables,\n  and configuration values can be substituted.\n\n_Try rconfig in your browser: click the Gitpod button, then `cd inst/examples` in the VS Code terminal to run the `Rscript` example from this README!_\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/analythium/rconfig)\n\n- [Install](#install)\n- [Another config package?](#another-config-package)\n- [Usage](#usage)\n  - [R command line usage](#r-command-line-usage)\n  - [Variable substitution](#variable-substitution)\n  - [Using with Rscript](#using-with-rscript)\n  - [Shiny](#shiny)\n  - [Plumber](#plumber)\n- [License](#license)\n\n\n## Install\n\n```{r eval=FALSE}\n# CRAN version\ninstall.packages(\"rconfig\")\n\n# Development version from R-universe\ninstall.packages(\"rconfig\", repos = \"https://analythium.r-universe.dev\")\n```\n\n## Another config package?\n\nThere are other R packages to manage configs:\n\n- [config](https://rstudio.github.io/config/) has nice inheritance rules, and it even scans parent directories for YAML config files\n- [configr](https://CRAN.R-project.org/package=configr) has nice substitution/interpolation features and supports YAML, JSON, TOML, and INI file formats\n\nThese package are fantastic if you are managing deployments at different stages of the life cycle, i.e. testing/staging/production.\n\nHowever, when you use `Rscript` from the command line, you often do not want to manage too many configuration files, but want a quick way to override some of the default settings.\n\nThe rconfig package provides various ways to override defaults, and instead of changing the active configuration (as in the config package), you can merge lists in order to arrive at a final configuration. These are very similar concepts, but not quite the same.\n\nThe rconfig package has the following features:\n\n- uses default configuration file\n- file based override with the `-f` or `--file` flags (accepts JSON, YAML, INI, and plain text files)\n- JSON string based override with the `-j` or `--json` flags\n- other command line arguments are merged too, e.g. `--cores 4`\n- heuristic rules are used to coerce command line values to the right type\n- R expressions starting with `!expr` are evaluated by default, this behavior can be turned off (same feature can be found in the yaml and config packages, but here it works with plain text and JSON too)\n- period-separated command line arguments are parsed as hierarchical lists, e.g. `--user.name Joe` will be added as `user$name` to the config list\n- nested configurations can also be flattened \n- command line flags without a value will evaluate to `TRUE`, e.g. `--verbose`\n- environment variables (`${VALUE}`), R global variables (`@{VALUE}`), and configuration values (`#{VALUE}`) can be substituted\n- differentiates verb/noun syntax, where verbs are sub-commands following the R script file name and preceding the command line flags (starting with `-` or `--`)\n\nThis looks very similar to what [littler](https://CRAN.R-project.org/package=littler), [getopt](https://CRAN.R-project.org/package=getopt), and [optparse](https://CRAN.R-project.org/package=optparse) are supposed to do. You are right. These packages offer amazing command line experience once you have a solid interface. In an iterative and evolving research and development situation, however, rconfig gives you agility.\n\nMoreover, the rconfig package offers various ways for substituting environment variables, R global variables, and even substituting configuration values. The [GetoptLong](https://CRAN.R-project.org/package=GetoptLong/vignettes/variable_interpolation.html) package has similar functionality but its focus is on command line interfaces and not configuration. Other tools, such as `sprintf`, [glue](https://CRAN.R-project.org/package=glue), [rprintf](https://CRAN.R-project.org/package=rprintf), and [whiskers](https://CRAN.R-project.org/package=whisker) are aimed at substituting values from R expressions.\n\n\nIf you are not yet convinced, here is a quick teaser.\nThis is the content of the default configuration file, `rconfig.yml`:\n\n```{verbatim lang=\"yaml\", file=\"rconfig.yml\"}\n```\n\nLet's use a simple R script to print out the configs:\n\n```{verbatim lang=\"r\", file=\"test.R\"}\n```\n\nNow you can override the default configuration using another file, a JSON string, and some other flags. Notice the variable substitution for user name!\n\n```{bash}\nexport USER=Jane\n\nRscript --vanilla test.R deploy \\\n  -f rconfig-prod.yml \\\n  -j '{\"trials\":30,\"dataset\":\"full-data.csv\"}' \\\n  --user.name $USER \\\n  --verbose\n```\n\nThe package was inspired by the config package, docker-compose/kubectl/caddy and other CLI tools, and was motivated by some real world need when managing background processing on cloud instances.\n\n## Usage\n\n### R command line usage\n\nOpen the project in RStudio or set the work directory to the folder root after cloning/downloading the repository.\n\n```{r}\nstr(rconfig::rconfig())\n\nstr(rconfig::rconfig(\n    file = \"rconfig-prod.yml\"))\n\nstr(rconfig::rconfig(\n    file = c(\"rconfig.json\",\n             \"rconfig-prod.txt\"),\n    list = list(user = list(name = \"Jack\"))))\n\nstr(rconfig::rconfig(\n    file = c(\"rconfig.json\",\n             \"rconfig-prod.txt\"),\n    list = list(user = list(name = \"Jack\")),\n    flatten = TRUE))\n```\n\nSet defaults in case some values are undefined (best to use `[[` notation \ninstead of `$` to avoid surprises):\n\n```{r}\nCONFIG \u003c- rconfig::rconfig(\n    file = \"rconfig-prod.yml\")\n\nrconfig::value(CONFIG[[\"cores\"]], 2L)   # set to 1L\nrconfig::value(CONFIG[[\"test\"]])        # unset\nrconfig::value(CONFIG[[\"test\"]], FALSE) # use default\n```\n\nThe default values are used to ensure type safety:\n\n```{r}\nstr(rconfig::value(CONFIG[[\"trials\"]], 0L))    # integer\nstr(rconfig::value(CONFIG[[\"trials\"]], 0))     # numeric\nstr(rconfig::value(CONFIG[[\"trials\"]], \"0\"))   # character\nstr(rconfig::value(CONFIG[[\"trials\"]], FALSE)) # logical\n```\n\nUsing alongside of the config package:\n\n```{r}\nconf \u003c- config::get(\n    config = \"production\",\n    file = \"config.yml\",\n    use_parent = FALSE)\n\nstr(rconfig::rconfig(\n    file = \"rconfig.yml\",\n    list = conf))\n```\n\n### Variable substitution\n\nThe rconfig package interprets 3 kinds of substitution patterns:\n\n- environment variables (`${VALUE}`): these variables are already present when the configurations is read from the calling environment or from `.Renviron` file in the project specific or home folder, set variables can be null or not-null\n- R global variables (`@{VALUE}`): the rconfig package looks for variables in the global environment at the time of configuration evaluation, however, expressions are not evaluated (unlike the `!expr` option for values)\n- configuration values (`#{VALUE}`): the configuration level variables are evaluated last, thus these values can refer to existing keys that are already substituted\n\nThe substitution pattern can set defaults or error messages, following [bash](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_02) and [Docker](https://docs.docker.com/compose/environment-variables/) conventions:\n\n|              | `a` is set \u0026 not null            | `a` set but null                |  `a` is unset         |\n|--------------|--------------------------------|-------------------------------|---------------------|\n| `${a:-b}`     | substitute `a`                   | substitute `b`                  |  substitute `b`       |\n| `${a-b}`      | substitute `a`                   | substitute null               |  substitute `b`       |\n| `${a:?b}`     | substitute `a`                   | error, exit                   |  error, exit        |\n| `${a?b}`      | substitute `a`                   | substitute null               |  error, exit        |\n\n\nThe following YAML example has all 3 kinds of variable substitution pattern:\n\n```{verbatim lang=\"yaml\", file=\"rconfig-sub.yml\"}\n```\n\nSet the following variables:\n```{r}\nSys.setenv(USER=\"Adele\")\nSys.setenv(ACCESS=\"admin\")\nType \u003c- \"simple\"\nLang \u003c- \"HU\"\n```\n\nThis is the substituted version:\n\n```{r echo=FALSE, results=\"asis\"}\n# variables only looked for in global env\nType \u003c\u003c- \"simple\"\nLang \u003c\u003c- \"HU\"\nSys.setenv(R_RCONFIG_FILE = \"rconfig-sub.yml\")\n# x \u003c- rconfig::rconfig(file = \"rconfig-sub.yml\")\nx \u003c- rconfig::rconfig()\nSys.unsetenv(\"R_RCONFIG_FILE\")\ncat(\"```yaml\\n\", yaml::as.yaml(x), \"```\", sep = \"\")\n```\n\n### Using with Rscript\n\nSet the work directory to the `inst/examples` folder cloning/downloading the repo.\n\nDefault config if found (the script has debug mode on):\n\n```{bash}\nRscript test.R\n```\n\nDefault with debug mode off:\n\n```{bash}\nR_RCONFIG_DEBUG=\"FALSE\" Rscript test.R\n```\n\nChange default config file:\n\n```{bash}\nR_RCONFIG_FILE=\"rconfig-prod.yml\" Rscript test.R\n```\n\nChange default config file and debug off:\n\n```{bash}\nR_RCONFIG_FILE=\"rconfig-prod.yml\" R_RCONFIG_DEBUG=\"FALSE\" Rscript test.R\n```\n\nUse file and other props to override default:\n\n```{bash}\nRscript test.R -f rconfig-prod.yml --user.name \"unreal_Zh5z*$#=\"\n```\n\nUse JSON string and other props to override default:\n\n```{bash}\nRscript test.R \\\n  -j '{\"trials\":30,\"dataset\":\"full-data.csv\",\"user\":{\"name\": \"real_We4$#z*=\"}}' \\\n  --user.name \"unreal_Zh5z*$#=\"\n```\n\nrconfig also interprets verb/noun syntax, where\nverbs are sub-commands following the R script file name\nand preceding the command line flags (starting with `-` or `--`):\n\n```{bash}\nRscript test.R deploy --user.name \"unreal_Zh5z*$#=\"\n```\n\nFor a more realistic but still small example, let's use the `iris` data and get summaries by species using command line arguments:\n\n```{bash}\nRscript iris.R --species virginica\n```\n\n```{bash}\nRscript iris.R --species setosa --verbose\n```\n\n```{bash error=TRUE}\nRscript iris.R --species maxima --verbose\n```\n\n```{bash error=TRUE}\nRscript iris.R\n```\n\nCheck out the [`iris_rlog.R`](inst/examples/iris_rlog.R) file to see an example with proper logging.\n\nAnother illustration using the `mtcars` data set to fit linear models to different variables:\n\n```{bash}\nRscript mtcars.R\n```\n\n```{bash}\nRscript mtcars.R --verbose --vars cyl\n```\n\n```{bash error=TRUE}\nRscript mtcars.R --verbose --vars cal\n```\n\n```{bash}\nRscript mtcars.R --vars cyl disp hp\n```\n\nLet's see how to use sub-commands:\n\n```{bash}\n## This will print messages:\nRscript commands.R model\n\n## This will not print messages:\nRscript commands.R model --silent\n```\n\n```{bash}\nRscript commands.R predict\n```\n\n```{bash error=TRUE}\nRscript commands.R fit\n```\n\n```{bash error=TRUE}\nRscript commands.R\n```\n\nHere is how to make the R script executable on Linux (of course you'll need rconfig installed for this to work):\n\n```{bash eval=FALSE}\nsudo cp ./inst/examples/commands.R /usr/local/bin/\nsudo chmod +x /usr/local/bin/commands.R\n```\n\nMake sure that the R script has the shebang (`#!/usr/bin/env Rscript`) as the 1st line, and now can drop the `Rscript` part and use the script as `commands.R model`.\n\n### Shiny\n\nAn example to configure a [Shiny app](https://shiny.posit.co/) with command line flags:\n\n```bash\nRscript shiny/app.R\n\nRscript shiny/app.R \\\n  --test \\\n  --value 1000 \\\n  --color 'pink' \\\n  --title 'Only Testing'\n```\n\nAn example to configure a Shiny app using the [golem](https://golemverse.org/) with command line flags:\n\n```r\n# app.R\nCONFIG \u003c- rconfig()\nyourpkg::run_app(\n  title = value(CONFIG$title, \"Hello Shiny!\"),\n  test = value(CONFIG$test, FALSE),\n  color = value(CONFIG$color, \"purple\"),\n  options = list(port = value(CONFIG$port, 8080)))\n```\n\n```bash\n## then in terminal\nRscript app.R \\\n  --test \\\n  --value 1000 \\\n  --color 'pink' \\\n  --title 'Only Testing' \\\n  --port 3838\n```\n\n### Plumber\n\nAn example to configure a [Plumber API](https://www.rplumber.io/) with command line flags:\n\n```bash\ncd plumber\n\nRscript index.R\n\n# httr::POST(\"http://127.0.0.1:8080/echo?msg=Cool\") |\u003e httr::content()\n# httr::GET(\"http://127.0.0.1:8080/test\") |\u003e httr::content()\n\nRscript index.R \\\n  --test \\\n  --port 8000 \\\n  --title 'The echoed message is'\n\n# httr::POST(\"http://127.0.0.1:8000/echo?msg=Cool\") |\u003e httr::content()\n# httr::GET(\"http://127.0.0.1:8000/test\") |\u003e httr::content()\n```\n\n## License\n\n[MIT License](./LICENSE)\n© 2022 Peter Solymos and Analythium Solutions Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanalythium%2Frconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanalythium%2Frconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanalythium%2Frconfig/lists"}