Skip to main content
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:
  1. The -token flag
  2. The CONSUL_HTTP_TOKEN environment variable
  3. The -token-file flag
  4. 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.
Never expose your ACL tokens in public repositories or logs. Treat them like passwords.

​
Quick Comparison

MethodConfigurationWhen to Use
-token flagCLI argumentOne-off commands or scripts
CONSUL_HTTP_TOKENEnvironment variableFrequent CLI use, avoids repetitive flags
-token-file flagFile containing tokenCentralized token management via file system
CONSUL_HTTP_TOKEN_FILEEnv var pointing to fileCombine 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)
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)
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.

Watch Video