Consul API client consul consul-api
0.1.3 Latest release released

💎 crystal-consul

Language Build Status GitHub release

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 "crystal-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.


  • [x] Agent
  • [x] KV Store
  • [x] Catalog
  • [x] Coordinates
  • [x] Events
  • [x] Health
  • [x] Snapshots
  • [x] 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


  github: rogerwelin/crystal-consul
  version: ~> 0.1.3
License MIT
Crystal 0.34.0


Dependencies 0

Development Dependencies 0

Dependents 0

Last synced .
search fire star recently