# Using Abseil Command-Line Flags Library (absl::Flags): A Complete Guide

> Master Abseil command-line flags library absl::Flags for C++ with this guide. Learn to define, parse, and query options efficiently using ABSL_FLAG and absl::ParseCommandLine.

- Repository: [Abseil/abseil-cpp](https://github.com/abseil/abseil-cpp)
- Tags: how-to-guide
- Published: 2026-07-16

---

**The Abseil Flags library provides a lightweight, high-performance way to define, parse, and query command-line options in C++ through the `ABSL_FLAG` macro and `absl::ParseCommandLine` API.**

The `absl::Flags` library, part of the `abseil/abseil-cpp` repository, offers a robust alternative to manual argument parsing. Using Abseil command-line flags library `absl::Flags`, developers can declare strongly-typed global variables that automatically populate from command-line arguments and integrate seamlessly with Abseil's logging system.

## Declaring Flags with ABSL_FLAG

Flags are declared at global scope using the `ABSL_FLAG` macro defined in **[`absl/flags/declare.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/declare.h)**. This macro instantiates an `absl::Flag<T>` object (defined in **[`absl/flags/flag.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/flag.h)**) and registers it in the global registry at static-initialization time.

The macro signature follows the pattern:

```cpp
ABSL_FLAG(type, name, default_value, "help string");

```

Each expansion creates a global variable named `FLAGS_<name>`. For example:

```cpp
#include "absl/flags/declare.h"
#include "absl/time/time.h"

ABSL_FLAG(bool, verbose, false, "Enable verbose output");
ABSL_FLAG(int, threads, 4, "Number of worker threads");
ABSL_FLAG(absl::Duration, timeout, absl::Seconds(30), "Connection timeout");

```

During static initialization, these definitions link themselves into a global registry managed by **[`absl/flags/internal/registry.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/internal/registry.h)**, making them available to the parser without explicit registration calls.

## Parsing Command-Line Arguments

Parsing is performed by calling `absl::ParseCommandLine`, declared in **[`absl/flags/parse.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/parse.h)** and implemented in **`absl/flags/parse.cc`**. This function scans `argv`, matches arguments against registered flags, performs type conversion, and updates the global flag values.

```cpp
#include "absl/flags/parse.h"

int main(int argc, char** argv) {
  // argc and argv are adjusted to remove consumed flag arguments
  absl::ParseCommandLine(argc, &argv);
  
  // Remaining argc/argv contain only positional arguments
  for (int i = 1; i < argc; ++i) {
    std::cout << "Positional: " << argv[i] << "\n";
  }
}

```

The parser recognizes `--name=value`, `--name value`, and boolean negation `--noname` patterns. When the user passes `--help` or `-h`, the parser automatically invokes the help generator from **[`absl/flags/usage.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/usage.h)**, printing a formatted table of all flags, their types, defaults, and documentation strings.

## Accessing and Modifying Flags at Runtime

After parsing, read flag values using **`absl::GetFlag`** and modify them using **`absl::SetFlag`**. Both functions provide thread-safe access to the underlying `Flag<T>` storage.

```cpp
#include "absl/flags/flag.h"

int main(int argc, char** argv) {
  absl::ParseCommandLine(argc, &argv);
  
  // Read access (lock-free)
  bool verbose = absl::GetFlag(FLAGS_verbose);
  int threads = absl::GetFlag(FLAGS_threads);
  
  // Runtime modification
  if (threads < 1) {
    absl::SetFlag(&FLAGS_threads, 4);
  }
  
  return 0;
}

```

`absl::GetFlag` takes the flag object directly (`FLAGS_name`), while `absl::SetFlag` requires the address (`&FLAGS_name`) to ensure explicit mutation intent. The implementation guarantees lock-free reads and writes under normal operation.

## Implementing Custom Flag Types

The library supports custom types through the marshalling layer in **[`absl/flags/marshalling.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/marshalling.h)**. To enable a custom type as a flag, provide `AbslParseFlag` and `AbslUnparseFlag` overloads in the same namespace as your type.

```cpp
#include "absl/flags/flag.h"
#include "absl/flags/marshalling.h"
#include "absl/strings/str_cat.h"

struct Point { int x; int y; };

// Required for marshalling
bool AbslParseFlag(absl::string_view text, Point* p, std::string* error) {
  if (absl::SimpleAtoi(text.substr(0, text.find(',')), &p->x) &&
      absl::SimpleAtoi(text.substr(text.find(',') + 1), &p->y)) {
    return true;
  }
  *error = "Expected format: x,y";
  return false;
}

std::string AbslUnparseFlag(const Point& p) {
  return absl::StrCat(p.x, ",", p.y);
}

// Now usable with ABSL_FLAG
ABSL_FLAG(Point, origin, {0, 0}, "Default origin coordinates");

```

`AbslParseFlag` converts the string representation to your type, returning `false` and populating `error` on failure. `AbslUnparseFlag` converts the type back to a string for help text and logging displays.

## Integration with Abseil Logging

The flags library shares its infrastructure with Abseil's logging subsystem. Logging-specific flags such as `FLAGS_log_prefix` and `FLAGS_v` are defined in **[`absl/log/flags.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/log/flags.h)** and parsed alongside your application flags.

This integration allows command-line control of log verbosity without additional code:

```bash
./my_app --v=2 --log_prefix=true --timeout=30s

```

Both user-defined flags and logging flags reside in the same `absl::flags_internal::FlagRegistry`, ensuring consistent parsing behavior and automatic help generation.

## Summary

- **Declaration**: Use `ABSL_FLAG` from [`absl/flags/declare.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/declare.h) to create global `FLAGS_<name>` variables of type `absl::Flag<T>`.
- **Parsing**: Call `absl::ParseCommandLine` from [`absl/flags/parse.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/parse.h) to populate flags and remove them from `argv`.
- **Access**: Use `absl::GetFlag` for reads and `absl::SetFlag` for thread-safe runtime modifications.
- **Extensibility**: Implement `AbslParseFlag` and `AbslUnparseFlag` to support custom types via the marshalling layer in [`absl/flags/marshalling.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/marshalling.h).
- **Integration**: Logging flags in [`absl/log/flags.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/log/flags.h) share the same parsing infrastructure for unified configuration.

## Frequently Asked Questions

### How do I declare a flag with a custom default value?

Use the `ABSL_FLAG` macro with your desired default as the third argument. For example, `ABSL_FLAG(int, port, 8080, "Server port")` declares an integer flag named `port` defaulting to 8080. The macro stores this default in the `absl::Flag<T>` instance created in [`absl/flags/flag.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/flag.h).

### Can I modify flag values after parsing?

Yes. After calling `absl::ParseCommandLine`, use `absl::SetFlag(&FLAGS_name, new_value)` to update the flag at runtime. This operation is thread-safe and lock-free according to the implementation in [`absl/flags/flag.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/flag.h).

### What happens when I pass `--help`?

When `absl::ParseCommandLine` encounters `--help` or `-h`, it automatically prints a formatted table of all registered flags including their types, default values, and help strings, then exits the program. This functionality is implemented in `absl/flags/parse.cc` using the registry from [`absl/flags/internal/registry.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/internal/registry.h).

### How do I use my own struct or class as a flag type?

Provide `AbslParseFlag` and `AbslUnparseFlag` functions for your type, typically in the same header where the type is defined. These functions convert between your type and string representations. Once defined, you can use `ABSL_FLAG(MyType, name, default, "help")` and the marshalling layer in [`absl/flags/marshalling.h`](https://github.com/abseil/abseil-cpp/blob/main/absl/flags/marshalling.h) will handle the conversions automatically.