# How to Use the gogcli Command Allowlist for Security

> Secure your CI pipelines with the gogcli command allowlist. Learn how to restrict CLI commands using GOG_ENABLE_COMMANDS or the enable-commands flag for enhanced security.

- Repository: [Peter Steinberger/gogcli](https://github.com/steipete/gogcli)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/steipete/gogcli/blob/main/internal/cmd/root.go), the `RootFlags` struct defines the `--enable-commands` flag with a default value pulled from the `GOG_ENABLE_COMMANDS` environment variable:

```go
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`](https://github.com/steipete/gogcli/blob/main/internal/cmd/enabled_commands.go) file contains the core enforcement logic. The `enforceEnabledCommands` function receives the Kong command context and the raw allowlist string:

```go
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:

```go
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:

```bash
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:

```bash
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:

```json5
{
  "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:

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

```

Lock a production service account to Drive operations only:

```bash
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:

```bash

# 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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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.