gnmic

gnmic (pronoun.: gee·en·em·eye·see) is a gNMI CLI client that provides full support for Capabilities, Get, Set and Subscribe RPCs with collector capabilities.

Documentation available at https://gnmic.openconfig.net

Development tool versions

versions.env is the shared source for Go, uv, Python, golangci-lint, GoReleaser, the Alpine base image, and integration-test image tags. Edit versions there when upgrading tooling. Any POSIX shell script can load and export all versions with:

. ./versions.env  # Run from the repository root, or use an absolute path.

Make includes this file, and CI loads its exports into GITHUB_ENV after checkout. Keep entries in the form export NAME=value, without quotes, spaces in values, or inline comments, so the file works in all three places.

The tracked .python-version file lets direct uv commands and other Python tools discover the same Python version. It is generated from PYTHON_VERSION in versions.env: after changing that setting, run make sync-versions and commit both files. make check-versions, the docs wrapper, and CI reject an out-of-date or missing generated file.

make build         # Build gnmic with the selected Go toolchain
make test          # Run tests in all Go modules with the same toolchain
make build-docker  # Build the integration-test image with shared build arguments
sh scripts/go.sh version
sh scripts/docker-build.sh -t gnmic:dev

The Go wrapper requires an installed Go 1.21+ and selects GO_VERSION through GOTOOLCHAIN, downloading that toolchain if needed. Docker builds require the GO_VERSION and ALPINE_VERSION build arguments; the wrapper supplies both. For a local GoReleaser invocation, source versions.env first so its Docker builds receive ALPINE_VERSION too.

Integration-test scripts use scripts/containerlab.sh, which loads versions after sudo so containerlab can expand image tags in the topology files. For a manual lab operation from the repository root, use, for example:

sh scripts/containerlab.sh deploy -t tests/clab/test_lab1.clab.yaml

Existing latest tags and partial versions are preserved in versions.env; they still track releases until changed to exact versions. Go module requirements in go.mod and Python compatibility requirements in pyproject.toml remain package metadata; resolved library dependencies stay in their native manifests and lockfiles. GitHub Action references stay pinned in workflow uses: fields, which require literal references. Host utilities such as Docker and containerlab are prerequisites; these scripts do not install them.

Documentation development

The site uses Zensical with its modern theme and the existing mkdocs.yml configuration. To start a live-reloading preview at http://127.0.0.1:8000, run:

make serve-docs

On Linux, macOS, or Windows via WSL, you need make and either curl or wget. The first run downloads a pinned version of uv, automatically detects your OS and architecture, and installs Python if needed. The uv binary, downloaded Python, dependencies, and package cache stay under the git-ignored .tools/docs/ directory; shell profiles are left untouched. Internet access is required for the initial setup. Later runs reuse these files. Zensical's build cache (.cache/) and output (site/) are also git-ignored.

make serve-docs DOCS_ADDR=0.0.0.0:8000  # Listen on all interfaces, e.g. in a dev container
make build-docs                       # Clean, strict production build in site/
make update-docs                      # Update the locked documentation dependencies

Commit uv.lock after reviewing an upgrade with make build-docs and the local preview. Normal builds use uv run --locked so local development and CI use the same dependency versions. The uv and Python versions come from versions.env; scripts/docs.sh checks .python-version is synchronized and passes the Python selection to uv through UV_PYTHON. Direct uv commands read .python-version.

The documentation workflow runs make deploy-docs, which builds with Zensical and publishes site/ to gh-pages using ghp-import through the same uv wrapper. It retains docs/CNAME and publishes on docs-* branch pushes, v* tags, and manual workflow runs. GitHub Pages continues to serve the root of gh-pages. make deploy-docs also works locally with repository push access and a configured Git author; it force-pushes the generated site to origin/gh-pages.

Search tags

Pages use Zensical's native search tags, following containerlab's approach. Tag filters connect related guides and examples: search for Prometheus, then select Output for configuration reference or Deployment for runnable examples. Search results also highlight matching terms when you open a page.

When adding a page, include YAML front matter with a category and the relevant topics or integrations, for example:

---
tags:
  - Output
  - Prometheus
  - Remote write
---

Reuse the spelling and capitalization listed in extra.tags in mkdocs.yml. Use Command for CLI reference, Input or Output for integration reference, Event processor for processors, and Deployment for deployment examples. Examples also carry their platform (Containerlab, Docker Compose, or Kubernetes) and any applicable Clustering or Pipeline tags. Add integration tags to both their reference pages and the examples that use them. Keep tags focused on the page's subject; mentions of a feature do not need their own tag. If a new topic needs a tag, register it in extra.tags and reuse an appropriate icon identifier from theme.icon.tag.

Tags are indexed automatically, including on pages with hide: [tags]. No additional plugin is needed. The unfinished blog is excluded with search: {exclude: true}; remove that front matter when it has useful content. After editing tags, run make build-docs and check the search filters in the local preview.

Features

• Full support for gNMI RPCs
  Every gNMI RPC has a corresponding command with all of the RPC options configurable by means of the local and global flags.
• Flexible collector deployment
  gnmic can be deployed as a gNMI collector that supports multiple output types (NATS, Kafka, Prometheus, InfluxDB,...).
  The collector can be deployed either as a single instance, as part of a cluster, or used to form data pipelines.
• Support gRPC tunnel based dialout telemetry
  gnmic can be deployed as a gNMI collector with an embedded tunnel server.
• gNMI data manipulation
  gnmic collector has data transformation capabilities that can be used to adapt the collected data to your specific use case.
• Dynamic targets loading
  gnmic support target loading at runtime based on input from external systems.
• YANG-based path suggestions
  Your CLI magically becomes a YANG browser when gnmic is executed in prompt mode. In this mode the flags that take XPATH values will get auto-suggestions based on the provided YANG modules. In other words - voodoo magic 🤯
• Multi-target operations
  Commands can operate on multiple gNMI targets for bulk configuration/retrieval/subscription.
• Multiple configuration sources
  gnmic supports flags, environment variables as well as file based configurations.
• Inspect raw gNMI messages
  With the prototext output format you can see the actual gNMI messages being sent/received. Its like having a gNMI looking glass!
• (In)secure gRPC connection
  gNMI client supports both TLS and non-TLS transports so you can start using it in a lab environment without having to care about the PKI.
• Dial-out telemetry
  The dial-out telemetry server is provided for Nokia SR OS.
• Pre-built multi-platform binaries
  Statically linked binaries made in our release pipeline are available for major operating systems and architectures. Making installation a breeze!
• Extensive and friendly documentation
  You won't be in need to dive into the source code to understand how gnmic works, our documentation site has you covered.

Quick start guide

Installation

bash -c "$(curl -sL https://get-gnmic.openconfig.net)"

Capabilities request

gnmic -a 10.1.0.11:57400 -u admin -p admin --insecure capabilities

Get request

gnmic -a 10.1.0.11:57400 -u admin -p admin --insecure \
      get --path /state/system/platform

Set request

gnmic -a 10.1.0.11:57400 -u admin -p admin --insecure \
      set --update-path /configure/system/name \
          --update-value gnmic_demo

Subscribe request

gnmic -a 10.1.0.11:57400 -u admin -p admin --insecure \
      sub --path "/state/port[port-id=1/1/c1/1]/statistics/in-packets"

Prompt mode

The prompt mode is an interactive mode of the gnmic CLI client for user convenience.

# clone repository with YANG models (Openconfig example)
git clone https://github.com/openconfig/public
cd public

# Start gnmic in prompt mode and read in all the modules:

gnmic --file release/models \
      --dir third_party \
      --exclude ietf-interfaces \
      prompt