# Ruby wrapper
The Ruby wrapper allows you to seamlessly interface with the Cloudimage API.
|  | Supported with Ruby 2.4+, JRuby, and TruffleRuby
github
|
| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
## Installation
Add this line to your application's Gemfile:
```sh
gem 'cloudimage'
```
And then execute:
```sh
$ bundle install
```
Or install it yourself as:
```sh
$ gem install cloudimage
```
## Usage
The only requirement to get started is your customer token. You can find it within your Admin interface.
In order to interact with Cloudimage, we'll first initialize a client service object:
```ruby
client = Cloudimage::Client.new(token: 'mysecrettoken')
```
The Cloudimage client accepts the following options:
| Option | Type | Additional info |
|---|
token | string | Required if cname is missing. |
cname | string | Required if token is missing. See CNAME. |
salt | string | Optional. See Security. Needed if you are using URL sealing or URL signatures. |
signature_length | integer | Optional. Integer value in the range 6..40. Defaults to 18. |
sign_urls | boolean | Optional. Defaults to true. See Security. |
aliases | hash | Optional. See URL aliases. |
The calling path on the client object returns an instance of Cloudimage::URI. It accepts the path to the image as a string and we we will use it to build Cloudimage URLs.
```ruby
uri = client.path('/assets/image.png')
```
Here are some common approaches for constructing Cloudimage URLs using this gem:
**Hash of params**
Pass a hash to `to_url`. Every key becomes a param in the final Cloudimage URL so this gives you the freedom to pass arbitrary params if need be.
```ruby
uri.to_url(w: 200, h: 400, sharp: 1, gravity: 'west', ci_info: 1)
# => "https://mysecrettoken.cloudimg.io/assets/image.png?ci_info=1&gravity=west&h=400&sharp=1&w=200"
```
**Chainable helpers**
Every param supported by Cloudimage can be used as a helper method.
```ruby
uri.w(200).h(400).gravity('west').to_url
# => "https://mysecrettoken.cloudimg.io/assets/image.png?gravity=west&h=400&w=200"
```
While every key passed into the `to_url` method gets appended to the URL, chainable helper methods will throw a `NoMethodError` when using an unsupported method.
```none
uri.height(200).to_url
# NoMethodError (undefined method `height' for #)
```
This is useful for catching typos and identifying deprecated methods in case Cloudimage's API changes.
**Method aliases**
The gem comes with a handful of useful aliases. Consult the Cloudimage::Params module for their full list.
```ruby
uri.debug.prevent_enlargement.to_url
# => "https://mysecrettoken.cloudimg.io/assets/image.png?ci_info=1&org_if_sml=1"
```
From the example above you can see that parameters that only serve as a flag don't need to accept arguments and will be translated into `param=1` within the final URL.
{% hint style="info" %}
For the full set of parameters and detailed implementation instructions, please consult the [github page](https://github.com/scaleflex/cloudimage-rb).
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.cloudimage.io/implementation/cms-plugins/ruby-wrapper.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.