Demo Using Tokens with the Consul CLI

In this guide, you’ll learn four ways to provide an ACL token to the Consul CLI. ACL tokens control access to Consul’s API, ensuring your operations are authorized. You can supply your token through:

The -token flag
The CONSUL_HTTP_TOKEN environment variable
The -token-file flag
The CONSUL_HTTP_TOKEN_FILE environment variable

For demonstration, we’ll use the bootstrap/master token c7142d25-a8b1-70ba-f521-189872e92c24. Be sure to substitute your own token.

Warning

Never expose your ACL tokens in public repositories or logs. Treat them like passwords.

Quick Comparison

Method	Configuration	When to Use
`-token` flag	CLI argument	One-off commands or scripts
`CONSUL_HTTP_TOKEN`	Environment variable	Frequent CLI use, avoids repetitive flags
`-token-file` flag	File containing token	Centralized token management via file system
`CONSUL_HTTP_TOKEN_FILE`	Env var pointing to file	Combine file management with environment configuration

1. Using the `-token` Flag

Supply the ACL token directly on the command line with -token.

consul acl policy create \
  -token c7142d25-a8b1-70ba-f521-189872e92c24 \
  -name "test-policy" \
  -rules @rules.hcl

This is ideal for ad-hoc operations or automation scripts where passing flags is acceptable.

2. Using the `CONSUL_HTTP_TOKEN` Environment Variable

Export the token once, then omit the -token flag in subsequent commands:

export CONSUL_HTTP_TOKEN=c7142d25-a8b1-70ba-f521-189872e92c24

Now run the same policy creation without specifying the token:

consul acl policy create \
  -name "test-policy" \
  -rules @rules.hcl

To verify permissions are enforced, unset the variable and rerun:

unset CONSUL_HTTP_TOKEN

consul acl policy create \
  -name "test-policy" \
  -rules @rules.hcl
# => Failed to create new policy: Unexpected response code: 403 (Permission denied)

Note

Using CONSUL_HTTP_TOKEN is convenient for CI/CD pipelines and local development shells.

3. Using the `-token-file` Flag

Store your token in a file (e.g., token.txt) and point the CLI at it:

cat token.txt
consul acl policy create \
  -token-file token.txt \
  -name "test-policy" \
  -rules @rules.hcl

This approach keeps tokens out of your command history.

4. Using the `CONSUL_HTTP_TOKEN_FILE` Environment Variable

Combine file-based tokens with environment variables to centralize configuration:

export CONSUL_HTTP_TOKEN_FILE=token.txt

consul acl policy create \
  -name "test-policy" \
  -rules @rules.hcl
# => failed to create new policy: Unexpected response code: 500 (Invalid Policy: A Policy with Name "test-policy" already exists)

Note

Ensure the token file has restrictive permissions (chmod 600 token.txt) to prevent unauthorized access.

Summary

Consul CLI supports ACL tokens via:

-token flag
CONSUL_HTTP_TOKEN environment variable
-token-file flag
CONSUL_HTTP_TOKEN_FILE environment variable

Choose the method that best fits your workflow. For interactive use or automation, environment variables often offer the cleanest experience.

Links and References

Watch Video

Watch video content

Quick Comparison

1. Using the -token Flag

2. Using the CONSUL_HTTP_TOKEN Environment Variable