Skip to the page

Reference

CLI reference

rykloud 0.1.0: organisations, projects, environments and what runs in them, with the same rules, prices and approvals as the console. Every command is an operation of the API.

Install and sign in

curl -fsSL https://get.rykloud.com/install.sh | sh     # macOS and Linux
irm https://get.rykloud.com/install.ps1 | iex          # Windows PowerShell
rykloud auth login

The install scripts check the release's signature and checksum first. Verifying by hand and every platform's archive: Install the CLI. Signing in: rykloud auth login and Authentication.

Contexts

A context names an organisation, and optionally a project, an environment and the Rykloud address, so commands need fewer flags. Each context has its own session.

rykloud contexts create acme --org "Acme Ltd" --use
rykloud contexts set --project web
rykloud contexts list

A flag beats the environment (RYKLOUD_ORG, RYKLOUD_PROJECT, RYKLOUD_ENV, RYKLOUD_CONTEXT), which beats the context. rykloud contexts.

Output for scripts

Tables are for people. -o json and -o yaml (or RYKLOUD_OUTPUT) print the API's answer for programs; -q prints only ids. With -o json, an error is one JSON line on standard error, and the exit code says what kind of error it was.

rykloud envs list -o json | jq -r '.environments[].name'
rykloud envs get staging -o yaml

Exit codes

Exit codes are stable within a major version of rykloud.

   0  done
   1  failed (or you answered no at a prompt)
   2  used wrongly: an unknown flag, a missing argument or confirmation
   3  not signed in, or the session ended: run rykloud auth login
   4  not found (or not yours to see)
   5  refused by a rule: a role, a limit, the payment gate, a protected resource;
      retrying will not help
   6  waiting for a person: a change or plan needs an approval you cannot give
   7  cannot reach Rykloud (network, address, timeout)
   8  Rykloud failed or is busy; retrying may help
  10  rykloud diff --exit-code found differences
 130  interrupted (Ctrl+C)

With -o json, an error is one JSON line on stderr:

  {"error":{"code":"refused","message":"...","exitCode":5}}

Environment variables

Configuration lives in $RYKLOUD_CONFIG_DIR, else $XDG_CONFIG_HOME/rykloud, else ~/.config/rykloud (%AppData%\rykloud on Windows): config.yaml holds contexts.

Sessions (a context's Rykloud session, and its Rykon Mail session) are kept in the system keychain (macOS Keychain, Windows Credential Manager, the Secret Service on Linux), or in credentials.json (mode 0600) in the same folder when there is no keychain.

  RYKLOUD_CONTEXT              the context to use
  RYKLOUD_ORG, RYKLOUD_PROJECT the organisation and project, by name or id
  RYKLOUD_OUTPUT               table, json or yaml
  RYKLOUD_TOKEN                an access token to use instead of a stored session (CI)
  RYKLOUD_MAIL_API             Rykon Mail's API address (rykloud mail)
  RYKLOUD_MAIL_ACCOUNT         the Rykon Mail account, by name or id
  RYKLOUD_MAIL_TOKEN           a Rykon Mail API key or service account access token,
                               used instead of the Rykon Mail session (CI)
  RYKLOUD_MAIL_SA_SECRET       a service account's secret, for
                               rykloud mail service-accounts token
  RYKLOUD_CREDENTIALS          file or keyring: force the credential store
  RYKLOUD_CONFIG_DIR           where configuration is kept
  RYKLOUD_NO_UPDATE_NOTIFIER   set to stop the notice of a newer version
  NO_COLOR                     set for no colour; FORCE_COLOR to force it

Global flags (every command)

--context
the context to use (env RYKLOUD_CONTEXT)
--no-color
no colour (also NO_COLOR=1)
--org
the organisation, by name or id (env RYKLOUD_ORG)
--project
the project, by name or id (env RYKLOUD_PROJECT)
-e, --env
the environment, by name or id (env RYKLOUD_ENV)
-o, --output
how to print results: table, json or yaml (env RYKLOUD_OUTPUT)
-q, --quiet
print only ids, or nothing; no progress or notices
-v, --verbose
say each request and the error codes behind messages

Commands