CLI, runtime and SDK

Envless ships three independent packages: @goenvless/cli, the terminal binary, @goenvless/env, the runtime your application imports, and @goenvless/sdk, the API client. They are not layered on each other and none is a wrapper around another, so picking the right one matters.

The SDK column holds for envless-sdk, the Python SDK, as well: the same API client with the same methods, installed with pip install envless-sdk. A Python application loads its variables with envless-env, the Python twin of @goenvless/env, or from the CLI through envless run -- python app.py or envless sync.

The same goes for envless-sdk, the Ruby SDK, installed with bundle add envless-sdk. A Rails or Rack application loads its variables with envless-env, the Ruby twin of @goenvless/env, or from the CLI through envless run -- bin/rails server or envless sync.

PHP has both too. envless/sdk is the API client, installed with composer require envless/sdk, and a Laravel, Symfony or plain PHP application loads its variables with envless/env, the PHP twin of @goenvless/env, or from the CLI through envless run -- php artisan serve or envless sync.

Command to method map#

Every envless command that changes workspace state has an SDK equivalent. The device operations further down do not, including logout, which revokes the session on the server.

Products, projects, environments#

Variables and versions#

Workspace, people and integrations#

What only the CLI can do#

These are device operations. They depend on a local filesystem, a terminal, or a browser round-trip, so the SDK deliberately has no equivalent.

What only the runtime can do#

@goenvless/env is the only package your application code imports, and the only one that puts decrypted values in front of that code:

What only the SDK can do#

A couple of things the CLI has no command for, plus several it will not do conveniently:

• Administer a workspace from inside a Cloudflare Worker, a Lambda or a container, with no binary to install and no filesystem to read. @goenvless/env/edge loads variables in those runtimes, but it administers nothing.
• Write to a workspace in CI with nothing but an API key. The same ev_sk_ key reaches the CLI and the runtime, but every CLI command that writes refuses it with Machine keys are read only.
• Compose many operations in one typed script, with pagination and typed errors handled for you.
• Verify an incoming webhook signature.
• Rotate a passphrase across both live variables and version history in one call.

What it will not do is load variables into your application. That is @goenvless/env.

Using them together#

The three coexist without interfering. A common split is the CLI for humans, the runtime for the app itself, and the SDK for automation, in the same repository:

# @goenvless/cli: a developer, at a terminal
npm i -g @goenvless/cli

envless login
envless link
envless run -- npm run dev

// @goenvless/env: the application reading its own configuration,
// started with node --import @goenvless/env/register
import { env } from '@goenvless/env/server'

const stripe = new Stripe(env.STRIPE_SECRET)

// @goenvless/sdk: scripts/provision.ts, run in CI with ENVLESS_TOKEN set to an ev_sk_ API key
import { createClient } from '@goenvless/sdk'

const envless = createClient()

const name = `preview-${process.env.PR_NUMBER}`

await envless.environments.create('api', { name, slug: name })

Every SDK method linked above has a Python twin and a Ruby twin under the same name in snake_case, and a PHP twin under exactly the same name, documented under Python, Ruby and PHP.