Environment variables

i

❗ To allow deno to access environment variables the --allow-env=<allow-env> flag is required. If the --allow-env flag is not provided, environment variables will be ignored if not marked as required.

Environment variables added with the .env() method will be validated when the command is executed. Only environment variables that are available for the executed command will be validated. Valid environment variables will be stored in the options object and for invalid or missing environment variables an error is thrown. They are also shown in the auto generated help.

Environment variable names will be camel cased. For example SOME_ENV_VAR=true will be parsed to { someEnvVar: true }.

i

❗ If an option with the same name is defined, the option will override the environment variable.

import { Command } from "https://deno.land/x/cliffy@v1.0.0-rc.3/command/mod.ts";

await new Command()
  .env("SOME_ENV_VAR=<value:number>", "Description ...")
  .action((options) => console.log(options))
  .parse(Deno.args);Copy

$ SOME_ENV_VAR=abc deno run --allow-env=SOME_ENV_VAR https://deno.land/x/cliffy@v1.0.0-rc.3/examples/command/environment_variables.ts
Error: Environment variable "SOME_ENV_VAR" must be of type "number", but got "abc".

$ SOME_ENV_VAR=1 deno run --allow-env=SOME_ENV_VAR https://deno.land/x/cliffy@v1.0.0-rc.3/examples/command/environment_variables.ts
{ someEnvVar: 1 }Copy

Global environment variables

Global environment variables are also available on all sub commands. You can add global environment variables either with the .env() method and the global option or with the .globalEnv() method.

import { Command } from "https://deno.land/x/cliffy@v1.0.0-rc.3/command/mod.ts";

await new Command()
  .env("SOME_ENV_VAR=<value:number>", "Description ...", { global: true })
  .globalEnv("SOME_OTHER_ENV_VAR=<value:number>", "Description ...")
  .action((options) => console.log(options))
  .command("hello", "world ...")
  .action((options) => console.log(options))
  .parse(Deno.args);Copy

Required environment variables

Required environment variables can be added with the required option. If a required environment variable is not defined on command line an error is thrown.

import { Command } from "https://deno.land/x/cliffy@v1.0.0-rc.3/command/mod.ts";

await new Command()
  .env("SOME_ENV_VAR=<value:number>", "Description ...", { required: true })
  .action((options) => console.log(options))
  .parse(Deno.args);Copy

$ deno run https://deno.land/x/cliffy@v1.0.0-rc.3/examples/command/environment_variables.ts
error: Missing required environment variable "SOME_ENV_VAR".

$ SOME_ENV_VAR=abc deno run --allow-env=SOME_ENV_VAR https://deno.land/x/cliffy@v1.0.0-rc.3/examples/command/environment_variables.ts
Error: Environment variable "SOME_ENV_VAR" must be of type "number", but got "abc".

$ SOME_ENV_VAR=1 deno run --allow-env=SOME_ENV_VAR https://deno.land/x/cliffy@v1.0.0-rc.3/examples/command/environment_variables.ts
{ someEnvVar: 1 }Copy

Hidden environment variables

Hidden environment variables can be added with the hidden option and will be not displayed in the auto generated help.

import { Command } from "https://deno.land/x/cliffy@v1.0.0-rc.3/command/mod.ts";

await new Command()
  .env("SOME_ENV_VAR=<value:number>", "Description ...", { hidden: true })
  .action((options) => console.log(options))
  .parse(Deno.args);Copy

Prefix

It is very common to prefix environment variables with a name like DENO_DIR and DENO_INSTALL_ROOT. With the prefix option you can ensure the prefix is remove before the value is added to the options object. This works also in combination with options.

import { Command } from "https://deno.land/x/cliffy@v1.0.0-rc.3/command/mod.ts";

await new Command()
  .env(
    "DENO_INSTALL_ROOT=<path:string>",
    "Set install root.",
    { prefix: "DENO_" },
  )
  .option(
    "--install-root <path:string>",
    "Set install root.",
  )
  .action((options) => console.log(options))
  .parse();Copy

$ DENO_INSTALL_ROOT=foo/bar deno run --allow-env=DENO_INSTALL_ROOT https://deno.land/x/cliffy@v1.0.0-rc.3/examples/command/environment_variables_prefix.ts
{ installRoot: "foo/bar" }Copy

← Types Help →

Edit this page on GitHub