smily_cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f157eb28c398c7038493c5c558f5faec807d8e2b89761046ba137f086049fb6c
+  data.tar.gz: ff3e7be3ae92f10ddbd32cb86764ca84b59b3b76ca92fc4fb07e3634890115c1
+SHA512:
+  metadata.gz: 0b165be215a87ccba5e4f9411bc94683d3894cf6d96da72646e0589d622f06e3088f43013dbb1a47d7b4802be8b2a188e47c550ff632e2678868a7867c36043e
+  data.tar.gz: 4cf8ffdcac8182837f1311949aa2f94902a6661f00467e546c28cd662977815f77e6f4c3801a736e3d610fb72d72df735b843e44d62db821aa5ba43ac7e3fe35

data/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3", "3.4"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rspec
+
+  rubocop:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - name: Run RuboCop
+        run: bundle exec rubocop --format github
+
+  brakeman:
+    name: Brakeman
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      # This is a plain Ruby gem (not a Rails app), so Brakeman needs --force.
+      # -z makes it exit non-zero if any security warning is found.
+      - name: Run Brakeman
+        run: bundle exec brakeman --force --no-progress --quiet -z
+
+  bundler-audit:
+    name: Bundler Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - name: Audit dependencies for known CVEs
+        run: bundle exec bundler-audit check --update

data/.rubocop.yml

@@ -0,0 +1,70 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "bin/**/*"
+    - "vendor/**/*"
+    - "tmp/**/*"
+    - "pkg/**/*"
+
+# We document with YARD; a class comment isn't always warranted.
+Style/Documentation:
+  Enabled: false
+
+# The CLI leans on descriptive multi-branch case/format methods; keep the
+# metrics as guardrails rather than hard style rules for this codebase.
+Metrics/AbcSize:
+  Max: 40
+Metrics/MethodLength:
+  Max: 30
+Metrics/ClassLength:
+  Max: 250
+Metrics/ModuleLength:
+  Max: 250
+  Exclude:
+    - "spec/**/*"
+Metrics/BlockLength:
+  # Thor groups its instance helpers in a `no_commands do ... end` block.
+  AllowedMethods:
+    - "no_commands"
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+Metrics/CyclomaticComplexity:
+  Max: 13
+Metrics/PerceivedComplexity:
+  Max: 13
+Metrics/ParameterLists:
+  Max: 6
+  # Keyword args are self-documenting at the call site and don't suffer the
+  # positional-argument ordering problem this cop guards against.
+  CountKeywordArgs: false
+
+# Our error classes take keyword args (status:, body:), so `raise Error.new(...)`
+# is intentional and clearer than the exploded form.
+Style/RaiseArgs:
+  Enabled: false
+
+# Endless methods and long single-purpose lines read fine here.
+Layout/LineLength:
+  Max: 120
+  AllowedPatterns:
+    - '\A\s*#' # long comment/URLs
+
+Style/EndlessMethod:
+  EnforcedStyle: allow_single_line
+
+# Heredocs and message strings frequently mix quote styles intentionally.
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+Style/WordArray:
+  Enabled: true
+
+# Guard clauses that raise with a message are clearer un-negated at times.
+Style/GuardClause:
+  Enabled: false
+
+# Specs use `expect { }.to raise_error { |e| ... }` blocks.
+Lint/AmbiguousBlockAssociation:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,65 @@
+## [Unreleased]
+
+- MCP `list` now speaks the API v3 filter DSL: `attribute[op]=value` applies an
+  operator (`eq`, `not_eq`, `gt`, `gteq`, `lt`, `lteq`, `in`, `matches`,
+  `does_not_match`) and repeating an attribute combines conditions with AND
+  (e.g. a numeric or date range). Values are coerced to numbers/booleans; ISO
+  8601 timestamps stay strings.
+- Fixed the `booking_discount_codes` / `booking_discount_code_usages` resources
+  to use their flat top-level v3 paths (were pointing at a nested
+  `booking/discount_codes` path).
+- Internal: the library now autoloads via Zeitwerk instead of hand-maintained
+  `require_relative` chains.
+- Tests: added VCR-cassette acceptance tests exercising the REST and MCP flows
+  end-to-end (list, Link-header pagination, 404 handling, operator/range filter).
+- Security: `auth client-credentials` / `refresh` / `exchange` no longer dump the
+  full token payload (including the refresh token) when their output is piped or
+  captured. The full payload is now opt-in via an explicit `-o json` /
+  `SMILY_OUTPUT=json`; the default stays access-token-only.
+- Fixed a spurious "results may be truncated" warning from `--all` / `--limit`
+  when a collection finished on exactly the `--max-pages` page; the warning now
+  fires only when a further page is actually being left behind.
+- Config: a structurally valid config file carrying a value `safe_load` refuses
+  (e.g. an unquoted date) now fails with a clean configuration error instead of
+  an uncaught YAML backtrace.
+- Argv parsing: a forgotten value for a global flag (`smily --token rentals
+  list`) now fails with a clear "Missing value for --token" error instead of
+  swallowing the subcommand into the flag (which produced a baffling "command
+  not found" or a request fired with a bogus value). Use `--flag=value` when a
+  value legitimately collides with a command name.
+
+## [0.1.0]
+
+Initial (unreleased) version: a command-line client for the BookingSync (Smily)
+API v3.
+
+- Per-resource commands (`list`, `get`, `create`, `update`, `delete`) for the
+  documented API v3 endpoints, generated from a resource registry.
+- Raw `smily api <method> <path>` escape hatch for any endpoint/verb, with
+  optional `--paginate`.
+- OAuth helpers: `auth client-credentials`, `auth refresh`, `auth exchange`,
+  `auth authorize-url`, `auth status`, `auth token`.
+- Config profiles (`smily config …`) stored at `~/.config/smily/config.yml`
+  (0600), with flag > env > profile resolution.
+- Account scoping via `--account-id` / `SMILY_ACCOUNT_ID` for
+  Client-Credentials-flow tokens.
+- Output formats: table (default on a TTY), json, yaml, csv, ndjson; sparse
+  fieldsets, filtering, sideloading and pagination (`--all`, `--limit`,
+  `--page`, `--per-page`).
+- MCP mode (`smily mcp`): talk to a BookingSync MCP server (Model Context
+  Protocol) over the Streamable-HTTP JSON-RPC 2.0 transport. Includes `info`,
+  `tools`, and a low-level `call`, plus `list`/`get`/`schema`/`resources`
+  convenience wrappers over the generic dispatcher tools, and `mcp login` for
+  its dedicated setup. Separate credential (`mcp_token`) and endpoint
+  (`mcp_url`, default `<base-url>/mcp`); `--account-id` scopes tool calls.
+- `whoami`, `resources`, `completion` (bash/zsh/fish) and `version` commands.
+- Built on the official `bookingsync-api` client.
+- Security: `--verbose` redacts `Authorization`/`client_secret`/tokens; config
+  written `0600` in a `0700` directory; warns when credentials would be sent
+  over non-HTTPS.
+- Reliability: `--max-pages` backstop on auto-pagination (default 1000);
+  `--limit` sizes the page request; `--retry N` retries 429s honoring
+  `Retry-After` / `X-RateLimit-Reset`.
+- Ergonomics: single-value global flags may precede the subcommand;
+  `create --path` for nested creates.
+- CI: `bundler-audit` dependency CVE scan.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Karol Galanciak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,387 @@
+# smily — BookingSync (Smily) API v3 CLI
+
+`smily` is an ergonomic, comprehensive command-line client for the
+[BookingSync (Smily) API v3](https://developers.bookingsync.com/reference).
+
+It aims to be *the* tool you reach for when you want to talk to API v3 from a
+terminal or a script:
+
+- **Per-resource commands** — `smily rentals list`, `smily bookings get 42`,
+  `smily clients create …` — for every documented endpoint.
+- **A raw escape hatch** — `smily api get <path>` reaches *anything* the API
+  exposes, with pagination and wrapping out of your way.
+- **OAuth built in** — client-credentials, refresh, and authorization-code
+  helpers; no need to hand-roll token requests.
+- **Config profiles** — keep tokens for multiple accounts/environments and
+  switch with `--profile`.
+- **Output that fits your workflow** — a readable table on a TTY, clean JSON
+  when piped, plus YAML, CSV and NDJSON.
+- **Pagination, filtering, sparse fieldsets, sideloading** — first-class flags.
+
+It is built on top of the official
+[`bookingsync-api`](https://github.com/BookingSync/bookingsync-api) gem, so the
+HTTP, JSON:API and error-handling behavior matches the reference client.
+
+## Installation
+
+```bash
+gem install smily_cli
+```
+
+Or with Bundler:
+
+```ruby
+gem "smily_cli"
+```
+
+This installs the `smily` executable.
+
+## Setup (first run)
+
+Once the gem is installed, get from zero to your first authenticated call in
+four steps:
+
+```bash
+# 1. Confirm the executable is on your PATH
+smily version
+
+# 2. Get an API token. For scripts/automation the Client Credentials flow is
+#    simplest: you need your application's Client ID and Secret from the
+#    BookingSync developer portal (https://www.bookingsync.com/oauth/applications).
+#    --save writes the token to the default profile at
+#    ~/.config/smily/config.yml (created 0600, since it holds secrets).
+smily auth client-credentials --client-id "$CLIENT_ID" --client-secret "$CLIENT_SECRET" --save
+
+# 3. Verify the token actually works (calls /me)
+smily auth status --check
+
+# 4. Make your first real call
+smily rentals list --limit 5
+```
+
+A Client-Credentials token can read across every account that authorized your
+app; pin one account with `--account-id <ID>` per call, or store it once:
+
+```bash
+smily config set account_id <ID>
+```
+
+Don't want to store anything? Every command also reads `--token` / `SMILY_TOKEN`
+directly, so `SMILY_TOKEN=… smily rentals list` works with no config file at
+all. See [Authentication](#authentication) for the Authorization-Code (per-user)
+flow and [Configuration & profiles](#configuration--profiles) for multiple
+environments.
+
+## Quick start
+
+```bash
+# 1. Get a token (Client Credentials flow) and save it to the default profile
+smily auth client-credentials --client-id "$CLIENT_ID" --client-secret "$CLIENT_SECRET" --save
+
+# 2. Explore
+smily resources                 # what can I talk to?
+smily rentals list --limit 5    # a readable table
+smily bookings list --filter status=booked from=2026-01-01
+
+# 3. Fetch one, as JSON
+smily rentals get 42 -o json
+
+# 4. Anything the resource commands don't cover
+smily api get rentals/42/bookings --paginate -o ndjson
+```
+
+## Authentication
+
+API v3 uses OAuth 2.0 Bearer tokens. A token can be supplied (in order of
+precedence) by:
+
+1. `--token` flag
+2. `SMILY_TOKEN` (or `BOOKINGSYNC_TOKEN`) environment variable
+3. the active config profile
+
+### Getting a token
+
+```bash
+# Client Credentials — app-level, public scope, reads across all authorized
+# accounts. Great for scripts. (Tokens last ~2h.)
+smily auth client-credentials --client-id ID --client-secret SECRET --save
+
+# Authorization Code — per-account access.
+smily auth authorize-url --client-id ID --redirect-uri https://app.example.com/cb --scope "rentals_read bookings_read"
+# (open the URL, approve, copy the ?code=… back)
+smily auth exchange --client-id ID --client-secret SECRET --code CODE --redirect-uri https://app.example.com/cb --save
+
+# Refresh an expiring token
+smily auth refresh --client-id ID --client-secret SECRET --refresh-token RT --save
+
+# Check what's configured (optionally validate against /me)
+smily auth status --check
+```
+
+`--save` stores the token (and any refresh token / client credentials) in the
+active profile so subsequent commands just work.
+
+### Scoping a Client-Credentials token to one account
+
+A Client-Credentials token spans every account that authorized your app. Pin a
+single account with `--account-id` (sent as the `account_id` query parameter),
+via `SMILY_ACCOUNT_ID`, or by storing it in a profile:
+
+```bash
+smily rentals list --account-id 12345
+smily config set account_id 12345 --profile acme
+```
+
+For Authorization-Code tokens the account is implicit, so this is a no-op.
+
+## Configuration & profiles
+
+Configuration lives in `~/.config/smily/config.yml` (override with
+`SMILY_CONFIG`; honors `XDG_CONFIG_HOME`). The file is written with `0600`
+permissions because it holds secrets.
+
+```bash
+smily config init                         # interactive: store a token + base URL
+smily config set token TOKEN --profile prod
+smily config set account_id 123 --profile prod
+smily config use prod                     # make "prod" the default profile
+smily config list                         # profiles + settings (secrets masked)
+smily config path                         # where's the file?
+```
+
+Use a specific profile per command with `--profile NAME`, or set
+`SMILY_PROFILE`.
+
+## Working with resources
+
+Every registered resource supports the same verbs:
+
+```bash
+smily <resource> list [options]
+smily <resource> get ID [options]
+smily <resource> create --data <json>       # not on read-only resources
+smily <resource> update ID --data <json>
+smily <resource> delete ID [--yes]
+```
+
+Run `smily resources` for the full catalog, or `smily <resource> help`.
+
+### Listing, filtering, pagination
+
+```bash
+smily bookings list --filter status=booked --filter from=2026-01-01
+smily rentals list --fields id name --limit 10
+smily rentals list --all -o ndjson           # every page, one JSON object per line
+smily rentals list --page 2 --per-page 50    # a specific page
+smily rentals list --include photos          # sideload associations
+```
+
+- `--filter k=v` / `--query k=v` — API query parameters (repeat or space-separate).
+  These are sent verbatim, so a resource's documented filters work directly
+  (`--filter status=booked from=2026-01-01`), and operator query params are
+  forwarded as-is where the endpoint supports them
+  (`--filter 'final_price[gteq]=600'`). For the *validated* operator/range DSL,
+  see [MCP mode](#advanced-filtering-operators--ranges).
+- `--fields a b c` — sparse fieldset (also limits table/CSV columns).
+- `--include a b` — sideload associations (returned under `linked`).
+- `--limit N` — stop after N records (follows pages as needed; also sizes the
+  page request to `min(N, 100)`).
+- `--all` — fetch every page.
+- `--page` / `--per-page` — fetch one specific page.
+- `--max-pages N` — hard backstop on auto-pagination (default 1000); the CLI
+  warns if it stops early.
+- `--retry N` — retry `429 Too Many Requests` up to N times, waiting for the
+  rate-limit window (`Retry-After` / `X-RateLimit-Reset`). Off by default.
+
+### Creating & updating
+
+Provide attributes as a JSON object; the `{ "<resource>": [ … ] }` envelope
+that v3 expects is added for you:
+
+```bash
+smily rentals create --data '{"name":"Villa Sunset","sleeps":6}'
+smily clients create --data @client.json         # from a file
+echo '{"sleeps":8}' | smily rentals update 42 --data -   # from stdin
+```
+
+For nested creates (e.g. a booking under a rental), point `--path` at the
+parent collection (the envelope key stays the resource's):
+
+```bash
+smily bookings create --path rentals/42/bookings --data @booking.json
+```
+
+## The raw `api` command
+
+`smily api <method> <path>` is the universal escape hatch — it can reach any
+endpoint, with any verb, and sends your body verbatim:
+
+```bash
+smily api get me
+smily api get rentals --query per_page=5
+smily api get bookings/123
+smily api post rentals --data '{"rentals":[{"name":"X"}]}'
+smily api get rentals --paginate -o json     # combine all pages into one array
+```
+
+By default it prints the raw JSON response envelope. With `--paginate` it
+follows pagination and prints the combined records.
+
+## MCP mode (`smily mcp`)
+
+Besides the REST API, `smily` can talk to a **BookingSync MCP server** (Model
+Context Protocol) — the same servers an AI agent connects to. This is a separate
+mode with its own credential (`mcp_token`) and endpoint (`mcp_url`, defaulting to
+`<base-url>/mcp`).
+
+```bash
+# One-time setup: store the MCP token (and optionally a non-default endpoint)
+smily mcp login "$MCP_TOKEN"
+smily mcp login "$MCP_TOKEN" --url https://www.bookingsync.com/mcp --profile prod
+
+# Handshake + capabilities, and discover the tools the server exposes
+smily mcp info
+smily mcp tools
+
+# Convenience wrappers that mirror the REST commands, over the generic
+# list / get / resources / resource_schema tools:
+smily mcp resources
+smily mcp list rentals --limit 5
+smily mcp list bookings --filter status=booked --account-id 42
+smily mcp get rentals 42
+smily mcp schema bookings
+
+# Low-level escape hatch — call any tool with a raw JSON argument object:
+smily mcp call list --args '{"resource":"rentals","limit":5}'
+smily mcp call resource_schema --args @args.json
+```
+
+The convenience wrappers resolve the generic tool names for you — they work
+against a server that exposes `list`/`get`/… as well as one that prefixes them
+(`api_v3_list`, `api_v3_get`, …).
+
+### Advanced filtering (operators & ranges)
+
+`smily mcp list` speaks the API v3 filter DSL. A plain `attribute=value` is an
+exact match; `attribute[op]=value` applies an operator; repeating an attribute
+combines the conditions with AND (e.g. a range). Operators: `eq`, `not_eq`,
+`gt`, `gteq`, `lt`, `lteq`, `in`, `matches`, `does_not_match` (exactly the set a
+resource reports via `smily mcp schema <resource>`).
+
+```bash
+# final_price > 1000
+smily mcp list bookings --filter 'final_price[gt]=1000'
+
+# 600 <= final_price < 800  (compound AND range)
+smily mcp list bookings --filter 'final_price[gteq]=600' --filter 'final_price[lt]=800'
+
+# starts on/after a date, and one of several references
+smily mcp list bookings --filter 'start_at[gteq]=2026-01-01T00:00:00Z' --filter 'reference[in]=A123,B456'
+```
+
+Numeric and boolean values are coerced automatically; ISO 8601 timestamps are
+kept as strings. Use `smily mcp schema <resource>` to see which attributes are
+filterable and the operators each accepts.
+
+Credentials/endpoint resolve like everything else — `--mcp-token` /
+`SMILY_MCP_TOKEN` / profile `mcp_token`, and `--mcp-url` / `SMILY_MCP_URL` /
+profile `mcp_url`. `--account-id` scopes tool calls to a single account (as the
+`account_id` tool argument), which is how a multi-account MCP token is pinned.
+Output honors `-o` just like the REST commands.
+
+Transport details: `smily` speaks the Streamable-HTTP JSON-RPC 2.0 transport,
+performing the `initialize` handshake (capturing the `Mcp-Session-Id`) and
+accepting either `application/json` or SSE-framed responses.
+
+## Output formats
+
+`-o, --output` selects the format. The default is a human-readable **table** on
+an interactive terminal, and **json** when the output is piped — so scripts get
+machine-readable data automatically.
+
+| Format   | Notes                                             |
+|----------|---------------------------------------------------|
+| `table`  | Aligned grid (collections) or key/value (single). |
+| `json`   | Pretty JSON — array for lists, object for `get`.  |
+| `yaml`   | YAML.                                             |
+| `csv`    | Header + rows; nested values become JSON.         |
+| `ndjson` | One compact JSON object per line (a.k.a. `jsonl`).|
+
+```bash
+smily rentals list -o csv --fields id name status > rentals.csv
+smily bookings list --all -o ndjson | jq 'select(.status=="booked")'
+```
+
+## Global options
+
+Single-value global flags work before or after the subcommand
+(`smily -o json rentals list` and `smily rentals list -o json` are equivalent).
+Array-valued flags (`--fields`, `--filter`) must follow the subcommand.
+
+| Flag | Env | Meaning |
+|------|-----|---------|
+| `--profile NAME` | `SMILY_PROFILE` | Config profile to use |
+| `--token TOKEN` | `SMILY_TOKEN` | OAuth access token (REST) |
+| `--mcp-token TOKEN` | `SMILY_MCP_TOKEN` | MCP access token (`smily mcp`) |
+| `--mcp-url URL` | `SMILY_MCP_URL` | MCP endpoint (default `<base-url>/mcp`) |
+| `--base-url URL` | `SMILY_BASE_URL` | API base (default `https://www.bookingsync.com`) |
+| `--account-id ID` | `SMILY_ACCOUNT_ID` | Scope to an account (client-credentials tokens) |
+| `--max-pages N` | `SMILY_MAX_PAGES` | Auto-pagination backstop (default 1000) |
+| `--retry N` | `SMILY_RETRY` | Retry 429s N times, honoring the rate-limit reset |
+| `-o, --output` | `SMILY_OUTPUT` | Output format |
+| `--fields a b c` | | Field/column selection |
+| `--no-color` | `NO_COLOR` | Disable ANSI color |
+| `-q, --quiet` | | Suppress status messages |
+| `-v, --verbose` | `SMILY_VERBOSE` | Log HTTP traffic to stderr (secrets redacted) |
+
+### Security notes
+
+- Config files are written `0600` in a `0700` directory; secrets are masked in
+  `smily config list` / `smily auth status`.
+- `--verbose` scrubs `Authorization` / `client_secret` / tokens from the logged
+  traffic, so verbose output is safe to share.
+- The CLI warns (like the GitHub CLI) if a credential would be sent over a
+  non-HTTPS endpoint.
+
+## Shell completion
+
+```bash
+smily completion bash > /usr/local/etc/bash_completion.d/smily
+smily completion zsh  > "${fpath[1]}/_smily"
+smily completion fish > ~/.config/fish/completions/smily.fish
+```
+
+## Exit codes
+
+`0` success · `1` generic/API error · `2` usage error · `3` auth error
+(401/403) · `4` not found (404) · `5` rate limited (429).
+
+## Using it as a library
+
+The library layer is usable without Thor:
+
+```ruby
+require "smily_cli"
+
+client = SmilyCli::Client.new(token: ENV["SMILY_TOKEN"])
+result = client.list("rentals", limit: 10)
+result.records            # => [ { "id" => 1, ... }, ... ]
+
+puts SmilyCli::Formatters.render(result, format: "json")
+```
+
+## Development
+
+```bash
+bin/setup          # install dependencies
+bundle exec rake   # run the specs and RuboCop
+bundle exec rspec  # just the specs
+bin/console        # an IRB session with the gem loaded
+```
+
+CI (GitHub Actions) runs the specs across Ruby 3.2–3.4, RuboCop, and Brakeman.
+
+## License
+
+Available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+# RuboCop is a development-only dependency; only define the task when present so
+# the gem still loads its Rakefile without it (e.g. in a production install).
+begin
+  require "rubocop/rake_task"
+  RuboCop::RakeTask.new
+rescue LoadError
+  task(:rubocop) { warn "rubocop is not available" }
+end
+
+task default: %i[spec rubocop]

data/exe/smily

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "smily_cli"
+
+begin
+  SmilyCli.cli.start(ARGV)
+rescue SmilyCli::Error => e
+  warn SmilyCli::Color.red("Error: #{e.message}")
+  exit e.exit_status
+rescue Interrupt
+  warn "\nAborted."
+  exit 130
+rescue Errno::EPIPE
+  # Downstream pipe closed (e.g. `smily ... | head`); exit quietly.
+  exit 0
+end