gcnf is a CLI tool that uses Google Sheets as a configuration source. It lets you store, retrieve, and inject configuration values from a Google Sheets spreadsheet into your applications and CI/CD pipelines.

Supported platforms: macOS (amd64, arm64), Linux (amd64, arm64), Windows.

Bash

curl https://raw.githubusercontent.com/NeuralInnovations/gcnf/refs/heads/master/install.sh | bash

Zsh

curl https://raw.githubusercontent.com/NeuralInnovations/gcnf/refs/heads/master/install.sh | zsh

Verify the installation:

gcnf version

Remove the installed binary:

# macOS / Linux
sudo rm /usr/local/bin/gcnf

# Windows
rm "$HOME/bin/gcnf.exe"

Remove stored credentials and cached data:

rm -rf ~/.gcnf

# 1. Install gcnf
curl https://raw.githubusercontent.com/NeuralInnovations/gcnf/refs/heads/master/install.sh | bash

# 2. Authenticate with your Google account
gcnf login

# 3. Set the Google Sheet document ID (found in the sheet URL)
gcnf config --sheetId YOUR_GOOGLE_SHEET_ID

# 4. Get a single configuration value
gcnf get --sheet Env --env Staging --category Database --name Host

# 5. Inject configuration into an .env template
gcnf inject .env.template > .env

Google Sheet Example

Every sheet must have Category and Name columns. All other columns represent environments (e.g. Env1, Staging, Production, Develop).

gcnf supports two authentication methods:

gcnf login

Opens a browser for Google OAuth2 authentication. The token is stored at ~/.gcnf/.token.

To remove the stored token:

gcnf logout

Set the GCNF_GOOGLE_CREDENTIAL_BASE64 environment variable to the Base64-encoded contents of your Google service account JSON key file:

export GCNF_GOOGLE_CREDENTIAL_BASE64=$(base64 < service_account.json)

Authenticate with Google via OAuth2. Opens a browser to complete the login flow.

gcnf login

Remove the stored OAuth2 token.

gcnf logout

View or set the Google Sheet ID that gcnf uses by default.

# View current sheet ID
gcnf config

# Set the sheet ID (persisted to ~/.gcnf/.google_sheet_id)
gcnf config --sheetId YOUR_GOOGLE_SHEET_ID
gcnf config -i YOUR_GOOGLE_SHEET_ID

Display the current configuration and credential status.

# Default YAML output
gcnf status

# JSON output
gcnf status --format json
gcnf status -f json

Example output:

credentials_status: user_token
google_credential_b64: empty
google_sheet_id: 1ykOxHza5fxa-HbXPPlSGfTSm2YKG0AteNhDHI6tntUk
name: gcnf
storage_config_file: ./gcnf_config.json
user_token_file: valid
version: 0.0.8

Download configuration data from a Google Sheet and cache it in a local file.

gcnf load --sheet Env --env staging
gcnf load -s Env -e staging
gcnf l -s Env -e production

Remove locally cached configuration files. Without flags, deletes all cache files. With --sheet and --env, deletes only that specific cache.

# Delete all cache files
gcnf unload
gcnf d

# Delete a specific cache
gcnf unload --sheet Env --env staging

Retrieve a specific configuration value from Google Sheets.

gcnf get --sheet Env --env staging --category Database --name Host
gcnf get -s Env -e staging -c Database -n Host
gcnf g -s Env -e staging -c Database -n Host

Read a configuration value using the gcnf:// URL format.

gcnf read "gcnf://Env/Staging/Database/ConnectionString"
gcnf r "gcnf://Env/Production/App/ApiKey"

URL format: gcnf://SHEET/ENV/CATEGORY/NAME

Read a template file, resolve all gcnf:// URLs and environment variable references, and print the result to stdout.

gcnf inject .env.template > .env
gcnf inject -o .env .env.template
gcnf i .env.template > .env

# Skip comment lines in output
gcnf inject -c .env.template > .env

Template syntax example (.env.template):

ENV_TABLE=UnitTests
ENV_CATEGORY_NAME=Category1
ENV_CATEGORY=$ENV_CATEGORY_NAME
ENV_NAME=unittest
ENV_TEST_NAME=Value2
ENV_VALUE_NAME=$ENV_TEST_NAME
ENV_1=hello
ENV_2=op://Env/$APP_ENV/Database/ConnectionString
ENV_3=gcnf://$ENV_TABLE/${ENV_NAME:?error_env_not_found}/${ENV_CATEGORY}/${ENV_VALUE:-Value1}
# support = comments
ENV_4="gcnf://$ENV_TABLE/$ENV_NAME/$ENV_CATEGORY/$ENV_VALUE_NAME"

Templates support:

• Environment variable expansion: $VAR, ${VAR}
• Default values: ${VAR:-default}
• Required variables: ${VAR:?error message}
• gcnf:// URLs for Google Sheets values
• Comment lines starting with #

Bundle the current service account credentials, sheet ID, and config file path into a single encoded token. This is useful in CI/CD environments where setting one variable is easier than setting several.

# First set up credentials and sheet ID, then generate:
export GCNF_GOOGLE_CREDENTIAL_BASE64=$(base64 < service_account.json)
export GCNF_GOOGLE_SHEET_ID=YOUR_SHEET_ID
gcnf token generate

The output token can then be used as GCNF_TOKEN in other environments:

export GCNF_TOKEN=<generated_token>

Discover what is available in the spreadsheet.

# List all sheet tabs
gcnf list sheets

# List environment columns in a sheet
gcnf list envs --sheet Env

# List categories in a sheet
gcnf list categories --sheet Env

Compare configuration values between two environments in the same sheet.

gcnf diff --sheet Env --env1 staging --env2 production
gcnf diff -s Env --env1 dev --env2 staging

Check a template file for missing variables, malformed gcnf:// URLs, and empty values. Exits with code 0 if valid, 1 if issues found.

gcnf validate .env.template

Generate shell completion scripts for bash, zsh, fish, or PowerShell.

# Bash (add to ~/.bashrc)
source <(gcnf completion bash)

# Zsh (add to ~/.zshrc)
source <(gcnf completion zsh)

# Fish
gcnf completion fish | source

# PowerShell
gcnf completion powershell | Invoke-Expression

Download and install the latest version of gcnf.

gcnf update

Print the current version.

gcnf version

These flags can be used with any command:

# Suppress all warnings/info during inject
gcnf inject --quiet .env.template > .env

# See diagnostic details (cache hits, API calls)
gcnf get --verbose --sheet Env --env staging --category Database --name Host

GCNF_GOOGLE_CREDENTIAL_BASE64 -- Default: (none)

Base64-encoded Google service account JSON key. Used for non-interactive (CI/CD) authentication.

GCNF_GOOGLE_SHEET_ID -- Default: (none)

The Google Sheets document ID. Found in the sheet URL: https://docs.google.com/spreadsheets/d/<ID>/

GCNF_STORE_CONFIG_FILE -- Default: ./gcnf_config.json

Path to the local config cache file created by gcnf load.

GCNF_CACHE_TTL -- Default: (none, cache never expires)

Duration after which cached data expires and is re-fetched from Google Sheets. Uses Go duration format: 30m, 1h, 24h, etc.

export GCNF_CACHE_TTL=1h

GCNF_TOKEN -- Default: (none)

Composite token that encodes credentials, sheet ID, and config file path into a single value. Generated with gcnf token generate. When set, it provides defaults for the three variables above. Individual environment variables take precedence over values decoded from GCNF_TOKEN.

gcnf resolves configuration in the following order (highest priority first):

1. Individual environment variables (GCNF_GOOGLE_CREDENTIAL_BASE64, GCNF_GOOGLE_SHEET_ID, GCNF_STORE_CONFIG_FILE)
2. Values decoded from GCNF_TOKEN
3. Persistent config files stored in ~/.gcnf/
4. Built-in defaults

export GCNF_GOOGLE_CREDENTIAL_BASE64=$(base64 < service_account.json)
export GCNF_GOOGLE_SHEET_ID=1ykOxHza5fxa-HbXPPlSGfTSm2YKG0AteNhDHI6tntUk

gcnf inject .env.template > .env

# Generate the token once (locally):
export GCNF_GOOGLE_CREDENTIAL_BASE64=$(base64 < service_account.json)
export GCNF_GOOGLE_SHEET_ID=1ykOxHza5fxa-HbXPPlSGfTSm2YKG0AteNhDHI6tntUk
gcnf token generate
# Copy the output and store it as a CI/CD secret

# In CI/CD, set only one variable:
export GCNF_TOKEN=<token_from_above>
gcnf inject .env.template > .env

gcnf stores the following files in ~/.gcnf/:

The local config cache is stored at the path specified by GCNF_STORE_CONFIG_FILE (default: ./gcnf_config.json in the current working directory).