> ## Documentation Index
> Fetch the complete documentation index at: https://docs.antasphere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> antasphere is the command-line client for your Antasphere account. One antasphere login signs you in with a code sent to your email and stores a personal API key in a local profile; every later command uses that profile. From the terminal you can check who you are, list and pick your organizations, manage files, and export an organization's data.

## Install

```bash theme={null}
npm i -g @antasphere/cli
```

The published package is a single self-contained bundle with no runtime dependencies.

## Sign in

```bash theme={null}
antasphere login                 # prompts for your email and the 6-digit mailed code
antasphere login --email you@example.com --key-name laptop --expires-days 90
antasphere whoami                # you, your organizations, the active one
antasphere logout                # revokes the key, clears the profile
```

The code proves the mailbox; the key it mints is shown exactly once and goes straight into the
profile. A first login with a new email address creates the account, its personal organization
and the key in one flow. Accounts with two-factor authentication enabled cannot log in from the
CLI: create an API key in the dashboard instead and pass it with `--api-key` or
`ANTASPHERE_API_KEY`.

`logout` revokes the stored key on the server and removes the profile.

## Configuration

Profiles live at `~/.config/antasphere/config.json` (or under `$XDG_CONFIG_HOME`), readable by
you alone since they hold the API key. `--profile <name>` selects one; `login` writes the selected
profile and marks it active. Each setting resolves in this order:

| Setting  | Precedence                                                                  |
| -------- | --------------------------------------------------------------------------- |
| Base URL | `--api-url` → `ANTASPHERE_URL` → profile → `https://account.antasphere.com` |
| API key  | `--api-key` → `ANTASPHERE_API_KEY` → profile                                |

## Commands

```bash theme={null}
antasphere login                          # email code → stored API key
antasphere logout                         # revoke the stored key, clear the profile
antasphere whoami                         # you, your organizations, the active one, scopes
antasphere org list                       # your organizations (active org marked *)
antasphere org use <id>                   # choose the organization tool CLIs work in
antasphere org use --unset                # back to the organization you logged in to
antasphere export [-o <path>]             # full organization export as a zip
antasphere files list                     # list files (newest first)
antasphere files upload ./report.pdf      # upload (name defaults to the basename)
antasphere files download <id> --out ./f  # download by id
antasphere files rm <id>                  # delete by id
```

A login is bound to one organization; `whoami` and `org list` mark it with `*`. To work in another
organization, log in again into a second profile: `antasphere --profile acme login`, the same
model as `gcloud` or `gh`.

`org use <id>` does something different: it stores the organization that the tool CLIs (the
`slideless` CLI, for example) work in when you use them after one Antasphere login, and it checks
the id against your memberships before storing it. `--unset` clears it, and a tool's own `--org`
flag overrides it per command.

`export` needs a key granted the opt-in `data:export` scope and an admin role in the organization;
the archive streams to disk (default `export-<yyyy-mm-dd>.zip`). Deleting an account is
deliberately not a CLI action: do it from the dashboard.

`files list` is paginated (50 per page by default, 100 at most):

| Flag                | Effect                                          |
| ------------------- | ----------------------------------------------- |
| `--limit <n>`       | Page size (1-100)                               |
| `--cursor <cursor>` | Resume from a previous page's `nextCursor`      |
| `--all`             | Follow `nextCursor` until every page is fetched |

Add `--json` to any command for machine-readable output. A failed request prints to stderr and
exits non-zero; a key without the right scope gets a clean `403` message.

## Example (agent-style)

```bash theme={null}
antasphere login --email agent@example.com     # once; the profile stores the key
antasphere whoami --json | jq .workspace.name
antasphere files upload ./out.csv --content-type text/csv --json | jq -r .file.id
```

Ephemeral environments can skip the config file entirely:

```bash theme={null}
export ANTASPHERE_URL=https://account.antasphere.com
export ANTASPHERE_API_KEY=ant_xxx_yyy
antasphere whoami --json
```