Skip to main content
alguna is the command-line client for the Alguna Public API. Each API operation is one command. Use it in shell scripts, in CI jobs, for one-off operations, and to explore the API from a terminal. It sets the Authorization and Alguna-Version headers, sends an idempotency key on writes, and retries failed requests only when a retry is safe. For the objects it works with, see How Alguna works.
For application code, use a language SDK. See SDKs.

​
Install

You can also download an archive for your system from the releases page. The package is @alguna/cli on npm. The source is alguna-io/cli on GitHub.

​
Log in

Create an API key in the Alguna dashboard under Settings → Connections → Developers → API keys. A key looks like <key_id>.<key_secret>. alguna login asks for the key and saves it in alguna/config.json in your user config directory, with mode 0600. On a terminal, the key is not shown while you type. In a script, use alguna login --api-key "$KEY", or send the key on stdin. alguna logout removes the saved key. A flag wins over an environment variable, and an environment variable wins over the saved key: To use the sandbox, set ALGUNA_BASE_URL=https://api.sandbox.alguna.io.
An API key is a secret. In CI, keep it in your secret store and pass it as ALGUNA_API_KEY.

​
Use

  • Path parameters are arguments. Query parameters and the top-level text, number and true/false fields of the request body are flags. alguna <resource> <operation> --help shows them.
  • --body sets the request body as JSON: inline, @file, or - for stdin. A field flag replaces the same field. Give object and list fields in --body.
  • The CLI writes indented JSON to stdout. -o ndjson writes one line for each item of a list.
  • --all gets every page. With -o json it writes one array after the last page. With -o ndjson it writes each page as it arrives. With --all, --limit is the most items in total.
  • --dry-run writes the request and sends nothing. The API key shows as [REDACTED].
A command that deletes data, moves money or cannot be reversed asks you to confirm. --yes skips the question. When stdin is not a terminal, --yes is necessary.

​
Idempotency and retries

Every command that is not a GET sends an Idempotency-Key. It is a new random key (UUID v4) on each run, or the key that you set with --idempotency-key. Every retry in that run sends the same key, so the API returns the first result and does not do the action again. Set your own key when you run a write again yourself, for example after a script stopped halfway. For how the API treats keys, see Idempotency. The exceptions are alguna events ingest, alguna credits track and alguna credits check. They send no key unless you set one, because the API identifies their work by the request body. It removes duplicate events by unique_id, and credits track draws credit once for the same unique_ids. A new key on each run would replace that identity on credits track, so a run repeated after a failure would draw credit twice. The CLI still retries these commands. alguna credits check with reserve needs --idempotency-key, because the key identifies the hold. The CLI retries after status 408, 429, 502, 503 or 504, and after a network error: a refused or reset connection, a connection closed before the response, or a timeout. It also retries a 409 that has a Retry-After header. The API sends that header only while a request with the same idempotency key is still running. A 409 without it is a real conflict. By default the CLI retries 2 times (3 attempts). --max-retries sets the number, and --max-retries 0 turns retries off. Between attempts it waits 1 second, then 2, then 4, up to 60 seconds, each with ±10% jitter. When the response has a Retry-After header (seconds or an HTTP date), it waits for that time instead, up to 60 seconds.

​
Timeouts

Each attempt has 60 seconds to get a response. A retry gets the full time again. --timeout sets a different time:

​
Errors and exit codes

On a terminal, an error is one line on stderr, such as Error: customer not found (HTTP 404, request req_123). The text is the API’s detail, else its title, else its message, else the HTTP status text. Otherwise, or with --json-errors, the error is one line of JSON with the status, the request ID and the response. For the error format and status codes, see Errors.

​
FAQ

Run alguna <resource> <operation> --help. Run alguna version to see the default API version.
Yes. Set ALGUNA_BASE_URL=https://api.sandbox.alguna.io, or pass --base-url.
Yes. See SDKs for the language SDKs.
Open an issue in alguna-io/cli. Alguna generates that repo from its API spec, so pull requests there are not merged.