How to Use the gogcli Command Allowlist for Security

The gogcli command allowlist restricts which top-level CLI commands can execute by setting the GOG_ENABLE_COMMANDS environment variable or using the --enable-commands flag, preventing unauthorized operations in CI pipelines and sandboxed environments.

The steipete/gogcli repository provides a command-line interface for Google services with built-in security controls. The command allowlist feature lets administrators lock down the tool to specific operations, ensuring that automated scripts and CI/CD pipelines can only execute pre-approved commands.

Understanding the gogcli Command Allowlist Architecture

The allowlist mechanism intercepts command execution before any Google API calls occur, validating the requested operation against a predefined set of permitted commands.

Flag and Environment Variable Definition

In internal/cmd/root.go, the RootFlags struct defines the --enable-commands flag with a default value pulled from the GOG_ENABLE_COMMANDS environment variable:

type RootFlags struct {
    EnableCommands string `help:"Comma-separated list of enabled top‑level commands (restricts CLI)" default:"${enabled_commands}"`
}

This design ensures that the allowlist can be configured globally via environment variables or overridden per-invocation using CLI flags.

Parsing and Enforcement Logic

The internal/cmd/enabled_commands.go file contains the core enforcement logic. The enforceEnabledCommands function receives the Kong command context and the raw allowlist string:

func enforceEnabledCommands(kctx *kong.Context, enabled string) error { … }

Inside this function, parseEnabledCommands processes the CSV input by trimming whitespace, converting to lowercase, and filtering empty entries:

func parseEnabledCommands(value string) map[string]bool { … }

Wildcard Support for Bypassing Restrictions

The allowlist supports two special values that bypass command restrictions:

• "*" - Enables all commands
• "all" - Equivalent to the wildcard asterisk

When either value appears in the parsed map, the enforcement check returns immediately without validating the specific command.

Configuring the gogcli Command Allowlist

You can configure the allowlist through three mechanisms, listed in order of precedence (highest to lowest).

Using the GOG_ENABLE_COMMANDS Environment Variable

Set the environment variable to a comma-separated list of allowed commands:

export GOG_ENABLE_COMMANDS=calendar,tasks
gog calendar list          # Executes successfully

gog gmail send --help      # Fails with: command "gmail" is not enabled

Passing the --enable-commands Flag

Override the environment variable for a single invocation:

gog --enable-commands=drive,contacts drive ls

This approach is useful in CI pipelines where you want to restrict specific jobs to specific operations while keeping broader permissions for other workflows.

Setting Allowed Commands in config.json

The gogcli tool reads configuration from a JSON5 file. Add the enabled_commands key to restrict operations persistently:

{
  "enabled_commands": "drive,contacts"
}

When both the environment variable and config file entry exist, the environment variable takes precedence, as implemented in the parser initialization logic.

Security Benefits of Restricting gogcli Commands

Implementing command restrictions provides several security advantages for production deployments:

• Least-privilege execution: Only explicitly listed commands can invoke Google API operations, reducing the blast radius of compromised credentials.
• Safe sandboxing for automation: CI/CD pipelines and third-party agents can run gogcli without risk of executing destructive operations like bulk deletion or unauthorized data export.
• Predictable CI behavior: Locking the CLI to read-only commands (such as gmail list or calendar get) ensures that test failures cannot trigger accidental email sending or file modifications.
• Auditable configuration: The allowlist configuration resides in environment variables or version-controlled config files, enabling security teams to review permitted operations through standard infrastructure-as-code practices.

Practical Examples for CI/CD and Sandboxing

These real-world scenarios demonstrate how to implement the allowlist in different security contexts.

Restrict a GitHub Actions workflow to read-only Gmail operations:

- name: Fetch unread emails
  env:
    GOG_ENABLE_COMMANDS: gmail
  run: gog --json gmail list --unread

Lock a production service account to Drive operations only:

export GOG_ENABLE_COMMANDS=drive
gog drive download --id $FILE_ID --output /tmp/backup.zip

Enable wildcard mode for administrative tasks while keeping restrictions on service accounts:

# Administrative override

export GOG_ENABLE_COMMANDS=all
gog admin audit-logs --since yesterday

Summary

• The gogcli command allowlist restricts top-level CLI commands through the GOG_ENABLE_COMMANDS environment variable or --enable-commands flag.
• Configuration parsing occurs in internal/cmd/enabled_commands.go, where the enforceEnabledCommands function validates commands against the parsed allowlist before execution.
• Special wildcard values "*" and "all" bypass restrictions for administrative flexibility.
• The allowlist supports environment variables, CLI flags, and JSON5 configuration files, with environment variables taking precedence.
• Implementing command restrictions enables least-privilege execution, safe automation sandboxing, and auditable security policies for CI/CD pipelines.

Frequently Asked Questions

What happens if I try to run a command not in the allowlist?

The CLI aborts execution before invoking any Google API calls and returns a usage error stating that the specific command is not enabled. This prevents unauthorized operations from accessing your credentials or data.

Can I use both the environment variable and the command-line flag simultaneously?

Yes. When both are present, the --enable-commands flag overrides the GOG_ENABLE_COMMANDS environment variable for that specific invocation. This allows temporary exceptions to persistent restrictions without modifying environment configuration.

Is the allowlist case-sensitive?

No. The parseEnabledCommands function in internal/cmd/enabled_commands.go converts all entries to lowercase before comparison, and the command name lookup uses the lower-cased version of the invoked command. This ensures that GOG_ENABLE_COMMANDS=Calendar matches the calendar command.

How do I completely disable the allowlist and allow all commands?

Set the allowlist value to either "*" or "all". Both values are treated as wildcards in the enforceEnabledCommands function, causing it to skip validation and permit any top-level command to execute.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}