Skip to main content

Install and Sign In

The CLI is a single zero-dependency Node script. Installing it takes one command, and signing in takes one more — a browser round-trip that mints a tenant-scoped credential without you ever pasting a key.

Requirements​

Node 18 or newer. The CLI uses only the Node standard library (fetch, fs, http, crypto), so there is nothing else to install and no dependency tree to audit.

Install​

npm install -g @autessa/cli
autessa version
autessa 0.3.1

Sign in​

autessa login
Opening your browser to sign in and choose a company…
Waiting for you to finish in the browser…

Successfully signed in.  you@example.com · tenant Acme Inc  (544 commands)
Try: autessa help   •   check later: autessa status

What happens:

  1. The CLI binds an ephemeral loopback port on 127.0.0.1 and opens /user/cli-login in your default browser with that port and a random state value.
  2. You sign in normally and pick which company the session should be scoped to.
  3. The server mints a tenant-scoped CLI credential and redirects back to the loopback with it. The state is verified before anything is stored.
  4. The credential is written to ~/.autessa/config, and the SDK manifest is fetched and cached.

Nothing is copied, pasted, or shown in the terminal. If the browser does not open on its own, the URL is printed for you to open manually.

The credential is tenant-scoped and self-expiring — roughly an eight-hour session, with no silent refresh. When it lapses, commands fail with "Session expired" and you run autessa login again. There is no long-lived CLI token to leak.

Check your session​

autessa status
Profile:  default
Endpoint: https://api.autessa.com
Status:   signed in ✓
User:     you@example.com
Tenant:   Acme Inc
Session:  valid until 2026-09-10T17:19:43
Live:     credential OK ✓

Live: is an actual round-trip against the server, so it distinguishes "my stored token has not expired yet" from "my token still works".

autessa whoami is an alias for the same command.

Sign out​

autessa logout

The credential is revoked server-side — it stops working immediately rather than lingering until its natural expiry — and the local profile is removed. If the server is unreachable the local profile is still cleared.

Profiles​

A profile is one saved sign-in: an endpoint, a tenant, and a credential. Profiles let you keep several companies or environments side by side without re-authenticating each time you switch.

autessa login --profile prod          # create or refresh a named profile
autessa login --profile staging
autessa profiles                      # list them
PROFILE         ENDPOINT                  COMPANY                 STATUS
default *       https://api.autessa.com   Acme Personal           signed in
prod            https://api.autessa.com   Acme Inc                signed in
staging         https://api.autessa.com   Acme Staging            session expired

* = default (used when --profile / $AUTESSA_PROFILE aren't set).
Change default:  autessa profiles use <name>
Per command:     autessa <command> --profile <name>   (or: export AUTESSA_PROFILE=<name>)

Selecting a profile​

Resolution order, highest priority first:

  1. --profile <name> on the command
  2. $AUTESSA_PROFILE
  3. The persisted default profile (autessa profiles use <name>), falling back to default
autessa agents all --profile prod              # one command
export AUTESSA_PROFILE=prod                    # this shell
autessa profiles use prod                      # persistently
--profile is the only flag that selects a profile. --name is deliberately left free so it can be an ordinary SDK argument — autessa qr-codes create --name "Launch poster" passes a name to the command, not to the profile system.

Removing a profile​

autessa logout --profile staging

Revokes that profile's credential and deletes it from the config. If it was the default, the default reverts to default.

Using an AI app? You don’t need the CLI for that: add the hosted Autessa connector by URL. See Coding agents.

Where things are stored​

PathContents
~/.autessa/configProfiles: endpoint, tenant, identity, and session credential per profile
~/.autessa/manifest.jsonCached SDK manifest — the entire command surface
~/.autessa/update-check.jsonLast update check, so the version nudge costs no network call

The config is JSON and safe to inspect. It contains a live credential, so treat it like any other credential file — do not commit it, and do not copy it between machines.

Staying current​

autessa update --check                 # compare installed vs latest, change nothing
autessa update                         # reinstall the latest
autessa update --version 0.3.0         # pin or roll back to a specific version
Installed:  autessa 0.3.1
Latest:     autessa 0.3.1  (up to date)

The CLI also prints a one-line "update available" nudge, at most once a day, when the server advertises a newer version than the one you have. Because the command surface comes from the manifest rather than the binary, an out-of-date CLI is usually a cosmetic problem — but the server can gate clients that fall too far behind.

Refreshing the command surface​

The manifest is cached, so a command added on the server is not visible until you refresh:

autessa --refresh help                 # re-fetch the manifest, then show help
autessa agents all --refresh           # re-fetch, then run

You rarely need this by hand. If you run a command the server no longer recognizes, the CLI refreshes automatically and asks you to re-run.