Install
Sign in
--api-key or ANTASPHERE_API_KEY.
logout revokes the stored key on the server, with the standing grants it minted for the tool
CLIs, and removes the profile. The keys each tool minted for this machine are the tool’s own and
stay valid: plain logout names them and logout --all revokes each one on its tool first, then
the hub key. A tool that refuses, or cannot be reached, keeps its key on this machine and is
named, and the command exits 3.
Configuration
Profiles live at~/.config/antasphere/config.json (or under $XDG_CONFIG_HOME), readable by
you alone since they hold the API key. A profile is an instance of the account service, named
for its host: cloud is the implicit one at https://account.antasphere.com, and a self-hosted
or local instance named with --api-url gets a profile of its own (localhost:3000). --profile <name> selects one; login writes the selected profile and marks it active. Each setting
resolves in this order:
Commands
One organization, everywhere
Your login is yours, not an organization’s: the same key reaches every organization you belong to. Which one a command acts on is settled the same way for every command, here and in the tool CLIs:--org <id or name>on the command, orANTASPHERE_ORGin the environment, names it for that command. A name is matched against your organizations, case-insensitively; when two of yours share a name the command lists their ids and asks for one.- Without either, the command acts on your default organization, the one your account
keeps on the server.
antasphere org use <id or name>sets it andantasphere org use --unsetclears it;whoamiandorg listmark it with*. Because it is stored on your account, the tool CLIs follow it too, on every machine you are signed in on.
login records the organization it signed you in to, for information only, and no command reads it.
The tools
antasphere tools prints one row per Antasphere tool: NAME SLUG URL OPEN IN CONNECTED.
OPEN IN lists the organizations of yours that open the tool to you (a tool Antasphere opens
to organizations itself reads restricted with how many of yours have it, and is listed only
when the organization the command runs in holds it). CONNECTED says
whether this machine holds a key for the tool minted through the current login, the key the
tool’s own CLI keeps in its file under ~/.config/antasphere/tools/; the tool is recognised by
its address, so a self-hosted instance of a tool is never confused with the cloud one. --json
carries the organizations denied too.
teams works on the teams of the organization: teams list and teams members <team>
(where <team> is the team’s slug or id) need a key with account:read; teams create, rename,
delete, add <team> <email> and remove <team> <email> need a key with account:write held by
an owner or an admin of the organization. See Teams.
tools access shows who in the organization may use each tool: TOOL MODE TEAMS, for
every tool or for the one named. tools access <tool> --everyone opens it to the whole
organization; --teams design,sales narrows it to those teams (by slug), and --teams "" leaves
it to the owners and admins, who always keep access. Setting needs a key with account:write held
by an owner or an admin. A tool Antasphere opens to an organization itself reads
(opened by Antasphere) in the TEAMS column and is listed only where Antasphere opened it; setting
it answers a sentence saying whom to ask.
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):
Billing
Your organization pays for what the Antasphere tools do in credits. Every organization starts with a balance; each priced action a tool performs takes its credits from it, and every movement is recorded in the organization’s credit ledger. Thebilling commands act on the organization
every command acts on (--org, else your default) and are open to its owners and admins.
billing accountshows the balance, the currency (markedlockedonce it can no longer change), the plan, a low-balance line when the balance falls below the notice threshold, the credits that expire soonest, the card on file, the Pro subscription, whether auto-recharge is on, and your organization’s referral code.billing ledgerlists one line per entry: the date, the kind (signup,promo,manual,debit,expiry, …), the signed amount, the balance after it, and its reference in words (the voucher code, the usage event, the payment, a referral reward taken back after a refund). A grant that expires says when. It takes--kind,--from,--toand the pagination flags below (--limit,--cursor,--all).billing usagetakes--from,--to(default: the last 30 days),--period day|month,--limitand--cursor.billing redeem <code>adds the voucher’s credits to the balance; a code can be unknown, inactive, expired, used up, or already redeemed by your organization, and the command says which.billing buy <credits>buys credits: one of the packs, or a custom amount. It prints the price and a link; open the link in a browser and pay on Stripe’s page, where a promotion code can be entered. The credits show on the balance once Stripe confirms the payment, and the page the browser comes back to confirms what was bought, what was paid and the invoice. With--auto-recharge, the card you pay with is kept and auto-recharge turns on once the payment lands (Stripe’s page asks you to agree to keeping the card); it is never implied, and an organization whose auto-recharge is already on keeps its card and its settings.billing invoiceslists one line per invoice: the date, its number, the amount, its status and the link to the invoice’s page. It takes the pagination flags below.billing planshows the plan and the Pro subscription (its status, and when it renews or ends).plan subscribeprints a link to Stripe’s page, where you subscribe to Pro; the plan shows asproonce Stripe confirms.plan cancelkeeps Pro until the end of the paid period, then the organization returns to free;plan resumetakes a pending cancellation back. Both are done on the account page, and the command says so.billing cardshows the card on file.card addprints a link to Stripe’s page, where you enter the card; it shows here once Stripe confirms.card removeis done on the account page (it also switches auto-recharge off), and the command says so.billing auto-rechargeshows the auto-recharge settings: whether it is on, the balance under which it buys credits (--threshold), how many credits one recharge buys (--credits), the most it may buy in a calendar month (--cap), and what it bought this month.on,offandsetare done on the account page, and the command says so.billing referralshows your organization’s referral code, to hand to someone who signs up.billing referral <code>registers the code of the organization that sent you, once and before your first purchase; the reward comes with that first purchase.
account, ledger, usage, invoices) need a key carrying billing:read. Keys
minted by antasphere login carry it; a key minted before billing existed never gains it, so log
in again if these commands answer 403. redeem, buy, card add, plan subscribe and
referral <code> need account:write: each hands back a page you finish in a browser (the
Checkout for credits, the card’s setup page, the subscription’s Checkout) or registers a code. What
changes money with no further confirmation stays on the account page and no key reaches it:
plan cancel, plan resume, card remove and the auto-recharge settings answer with the page
to open instead.
Managing the price book, the plan tiers, credit grants and vouchers is an Antasphere operator
matter, not covered here.
Add --json to any command for machine-readable output. A failed request prints to stderr and
exits non-zero: 1 for a usage or wire error, 3 when the server refused (a key without the right
scope, a role the action needs, a suspended organization, a tool that would not revoke a key).
Demo links
On a demonstration or test installation of Antasphere, an owner of an organization can make a link that signs one of its demonstration accounts in without a password (Demo links). Demo links are off on account.antasphere.com: there the three commands below answerDemo sign-in is off on this instance (DEMO_SIGN_IN).
antasphere login stored: demo links
are made by an owner who signed in with their password. Each command signs in as the owner for its
own length and signs out when it ends, whatever happened. The owner’s address is --owner-email
or ANTASPHERE_OWNER_EMAIL; the password is ANTASPHERE_OWNER_PASSWORD or, with
--owner-password-stdin, the first line of stdin. There is no password flag (a password on a
command line lands in the shell history), and nothing (address, password, session) is written to
the profile. The installation comes from the usual --api-url / ANTASPHERE_URL / profile, and
the organization from --org <id or name>, resolved among the owner’s own organizations on
that installation: without it the commands act on the owner’s default organization there. An
owner with a second
factor cannot use these commands: make that owner’s links on the account site.
demo link makes ONE link per --email and prints, for each, one URL per --path, all
opening that member’s link; the first --path is the link’s own page. With --tool, every URL
ends with &tool=<slug> and opens that tool, on that page, as the member. A member the
installation refuses does not stop the others: the command names who was refused and why, and
exits 1. Each page is checked before any sign-in. The human output is the person, the tool, the
expiry, then the URLs one per line; --json is
{ passes: [{ pass, links: [{ path, url }] }], refused: [{ email, code, message }] }. The URLs
are the only place the link’s secret ever appears: keep them like a password until they expire.
The installation allows three sign-ins per ten seconds from one address. A script that runs
several demo commands in a row meets that limit: the command waits it out (a few seconds, three
times at most) and says so on stderr. Name every member on ONE demo link to sign in once.
demo list prints each link’s id, the person’s address, the tool, the page, the expiry, the
revocation, the last use and the number of uses (--json: { passes }). demo revoke <id>
revokes a link and ends every session it opened (--json: the revoked link).
The refusals are the installation’s own sentences: no member of the organization holds that
address; a link cannot open another owner’s account; the address is not a demonstration address;
the account has not confirmed its address; the account has a second factor; the person belongs to
another organization; no tool of the installation has that slug; the page is not a path. An admin
or a member who signs in reads Only an owner of this organization manages demo links: the account that signed in is not one.