Skip to content
Crystal client for Consul (
Branch: master
Clone or download
Latest commit 2beb4a0 Aug 20, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples adding examples Aug 19, 2019
spec minor test refactoring Aug 20, 2019
src adding examples Aug 19, 2019
.editorconfig init Aug 4, 2019
.gitignore init Aug 4, 2019
.travis.yml wip: implement consistency and url parameters Aug 19, 2019
LICENSE init Aug 4, 2019 adding examples Aug 19, 2019 more examples Aug 19, 2019
shard.yml project info Aug 8, 2019

💎 crystal-consul

Language Build Status

Crystal client for Consul HTTP API. For more information about the Consul HTTP API, go here. Crystal-consul does not use any depenencies outside stdlib, hence no transitive dependencies when you include it in your project.


  1. Add the dependency to your shard.yml:

        github: rogerwelin/crystal-consul
  2. Run shards install

Example Usage

require "consul"

# create a default client
c = Consul.client()

# create a key
c.kv.create_key("stage/service-example/version", "1")
c.kv.create_key("stage/service-example/tag", "master")

# read key
# Consul::Types::KV::KvPair(@key="stage/service-example/version", @value="1")

# you can also get keys recursively
c.kv.get_key("stage", recurse: true)
# [Consul::Types::KV::KvPair(@key="stage/service-example/tag", @value="master"), Consul::Types::KV::KvPair(@key="stage/service-example/version", @value="1")]

# register a service on the local agent
service =
service.service = "service-example"
service.tags = ["master"]
service.port = 9922


For more examples and usage view the example page

Project Status

Implemented endpoints implements all consistency modes, filter options and query parameters as specified by Consul HTTP API doc.


  • Agent
  • Catalog
  • Coordinates
  • Events
  • Health
  • KV Store
  • Snapshots
  • Status


  • ACLs
  • Config
  • Connect
  • Operator
  • Prepared Queries
  • Sessions
  • Transactions


Only a working Crystal installation and Docker is required. Project does not use mocks, instead all endpoints are tested against a running Consul docker container.

  1. Run docker run -d -p 8500:8500 consul:1.5.1
  2. Run crystal spec from the project root


Pull requests are very much appreciated! When you create a PR please ensure:

  • All current tests pass
  • To run crystal tool format on added code
  • To add tests for your new features, if applicable
  • To add doc comments for new api features you add
  1. Fork it (
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


You can’t perform that action at this time.