Ciris

Ciris

  • Blog
  • API Docs
  • Documentation
  • GitHub

›Documentation

Documentation

  • Overview
  • Quick Example
  • Configurations
  • Modules

Modules

The following sections describe the additional modules.

circe

The ciris-circe module provides ConfigDecoders for JSON using circe.

import ciris._
import ciris.circe._
import io.circe.Decoder

case class SerialNumber(value: String)

object SerialNumber {
  implicit val serialNumberDecoder: Decoder[SerialNumber] =
    Decoder[String].map(apply)

  implicit val serialNumberConfigDecoder: ConfigDecoder[String, SerialNumber] =
    circeConfigDecoder("SerialNumber")
}

env("SERIAL").as[SerialNumber]
// res0: ConfigValue[Effect, SerialNumber] = ConfigValue$1146504084

circe-yaml

The ciris-circe-yaml module provides ConfigDecoders for YAML using circe-yaml.

import ciris._
import ciris.circe.yaml._
import io.circe.Decoder

case class SerialNumber(value: String)

object SerialNumber {
  implicit val serialNumberDecoder: Decoder[SerialNumber] =
    Decoder[String].map(apply)

  implicit val serialNumberConfigDecoder: ConfigDecoder[String, SerialNumber] =
    circeYamlConfigDecoder("SerialNumber")
}

env("SERIAL").as[SerialNumber]
// res2: ConfigValue[Effect, SerialNumber] = ConfigValue$883384633

enumeratum

The ciris-enumeratum module provides ConfigDecoders for enumeratum enumerations.

For regular Enums, also mix in CirisEnum to derive a ConfigDecoder instance.

import ciris.env
import enumeratum.{CirisEnum, Enum, EnumEntry}
import enumeratum.EnumEntry.Lowercase

sealed trait Suit extends EnumEntry with Lowercase

object Suit extends Enum[Suit] with CirisEnum[Suit] {
  case object Clubs extends Suit
  case object Diamonds extends Suit
  case object Hearts extends Suit
  case object Spades extends Suit

  val values = findValues
}

env("SUIT").as[Suit]
// res4: ciris.ConfigValue[ciris.package.Effect, Suit] = ConfigValue$641702504

For ValueEnums, also mix in the matching CirisValueEnum to derive a ConfigDecoder instance.

import ciris.env
import enumeratum.values.{StringCirisEnum, StringEnum, StringEnumEntry}

sealed abstract class Color(val value: String) extends StringEnumEntry

object Color extends StringEnum[Color] with StringCirisEnum[Color] {
  case object Red extends Color("red")
  case object Green extends Color("green")
  case object Blue extends Color("blue")

  val values = findValues
}

env("COLOR").as[Color]
// res6: ciris.ConfigValue[ciris.package.Effect, Color] = ConfigValue$235471128

http4s

The ciris-http4s module provides ConfigDecoders for ip4s and http4s types.

import ciris.env
import ciris.http4s._
import com.comcast.ip4s.Host
import com.comcast.ip4s.Port
import org.http4s.headers.Origin
import org.http4s.Uri

env("HOST").as[Host]
// res8: ciris.ConfigValue[ciris.package.Effect, Host] = ConfigValue$466151080
env("PORT").as[Port]
// res9: ciris.ConfigValue[ciris.package.Effect, Port] = ConfigValue$895974823
env("ORIGIN").as[Origin]
// res10: ciris.ConfigValue[ciris.package.Effect, Origin] = ConfigValue$2113785885
env("URI").as[Uri]
// res11: ciris.ConfigValue[ciris.package.Effect, Uri] = ConfigValue$1347043549

http4s-aws

The ciris-http4s-aws module provides a way to read decrypted values from the AWS Systems Manager (SSM) Parameter Store using the http4s-aws library. Following is an example of how parameter values can be retrieved. Note parameter values are wrapped in Secret by default since they are usually sensitive.

import cats.effect.IO
import cats.effect.IOApp
import ciris._
import ciris.http4s.aws.AwsSsmParameters
import com.magine.aws.Region
import com.magine.http4s.aws.CredentialsProvider
import org.http4s.ember.client.EmberClientBuilder

object Main extends IOApp.Simple {
  case class Config(username: String, password: Secret[String])

  object Config {
    def fromParameters(parameters: AwsSsmParameters[IO]): IO[Config] =
      (
        env("USERNAME"),
        parameters("password")
      ).parMapN(apply).load[IO]
  }

  override def run: IO[Unit] =
    EmberClientBuilder.default[IO].build.use { client =>
      CredentialsProvider.default(client).use { provider =>
        val parameters = AwsSsmParameters(client, provider, Region.EU_WEST_1)
        Config.fromParameters(parameters).flatMap(IO.println)
      }
    }
}

refined

The ciris-refined module provides ConfigDecoders for refined refinement types.

import ciris.env
import ciris.refined._
import eu.timepit.refined.types.numeric.PosInt

env("POS_INT").as[PosInt]
// res14: ciris.ConfigValue[ciris.package.Effect, PosInt] = ConfigValue$1194801260

squants

The ciris-squants module provides ConfigDecoders for squants quantities.

import ciris.env
import ciris.squants._
import squants.market.Money

env("MONEY").as[Money]
// res16: ciris.ConfigValue[ciris.package.Effect, Money] = ConfigValue$646749714
← Configurations
  • circe
  • circe-yaml
  • enumeratum
  • http4s
  • http4s-aws
  • refined
  • squants

Copyright © 2017-2025 Viktor Rudebeck.
Icon designed by Freepik from Flaticon.