Skip to content

Trek is a CLI/ncurses explorer for HashiCorp Nomad clusters.


Notifications You must be signed in to change notification settings


Repository files navigation


Trek is a CLI/ncurses explorer for HashiCorp Nomad clusters.

In Action


Binary Release

Get to revisions, and download a binary.

From Source

git clone
cd trek
make trek


TL;DR Start ./trek -help to get the usage prompt.


The CLI can be used without a UI. This allows scripting to access IP, ports, and other info exposed by Nomad.


Here's a list of options available:

  • nomad-address: address of the nomad cluster

  • list-jobs: list jobs running on the cluster
λ ./trek -list-jobs
* example
* example34

NOTE : this option also works in conjunction with display-format

  • job: select a specific job
λ trek -job example34
* cache34
* cache56

  • task-group: select a specific task group
λ trek -job example34 -task-group cache56
* example34.cache56[0]

  • allocation: select a specific allocation number
λ trek -job example34 -task-group cache56 -allocation 0
(0) redis5
(1) redis6

  • task-name: select a specific task name
λ trek -job example34 -task-group cache56 -allocation 0 -task-name redis6
* Name: redis6
* Node Name: feynman.local
* Node IP:
* Driver: docker
        * image: redis:3.2
        * port_map: [map[db:6379]]
* Dynamic Ports: 24832 (db)

  • display-format: Use the Go templating language to format output when describing a specific job, task group, allocation or task
    • Context-specific data made available:
      • Job
        • TaskGroups (array of task groups): task groups part of the job definition
      • Task Group
        • Allocations (array of allocations): allocations run by that task group
      • Allocation
        • IP (string): node onto which we're running the selected allocation
        • Tasks (array of tasks): tasks being run by that allocation
      • Task
        • IP (string): node onto which we're running the selected task
        • Network: network information (like ports)
        • Environment: environment variables provided to the task
    • Available functions:
      • {{Debug <x>}} : show raw representation of the data <x>
      • {{DebugAll}} : show raw representation of everything provided to the template
    • Examples:
λ trek -job example34 -task-group cache56 -allocation 0 -task-name redis6 -display-format "{{DebugAll}}"
DEBUG ALL: {IP: Network:{Ports:map[db:{Value:23109 Reserved:false}]} Environment:map[FOO_BAR:{Value:baz_bat}]}

λ trek -job example34 -task-group cache56 -allocation 0 -task-name redis6 -display-format "{{Debug .Environment}}"
DEBUG: map[FOO_BAR:{Value:baz_bat}]

λ trek -job example34 -task-group cache56 -allocation 0 -task redis6 -display-format "{{range .Network.Ports}}{{$.IP}}:{{.Value}}{{println}}{{end}}"

ncurses UI

./trek -ui=true

Trek Configuration File


{ "Environments" : [ { "Name" : "development" , "Address" : "" }


  • Environments: List of environments (given a name and address) Trek can connect to


  • How do I ssh into an allocation's node?

    λ ssh $(trek -job ... -task-group ... -allocation 0 -display-format "{{.IP}}")

Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so I don't break it in a future version unintentionally.
  • Commit.
  • Send me a pull request. Bonus points for topic branches.


Copyright (c) 2019 Franck Verrot. MIT LICENSE. See LICENSE for details.