The current API requires CLI v0.27.0 or later. Update older installations before managing resources. Scripts that parse JSON responses must also use the current resource fields and wrappers.
basaltic is the command-line client. It is the shortest path to driving the
platform from a terminal or a CI job, and it speaks the same API as the SDKs.
Install
/usr/local/bin when that is
writable or ~/.local/bin otherwise. Read it first if you would rather — it is
install.sh in the
repository, and that URL serves the same file.
go install github.com/basaltic-sh/cli@latest works if you have Go.
To update:
BASALTIC_NO_UPDATE_CHECK=1 turns it off.
Command shape
basaltic lb is basaltic loadbalancer, basaltic net is
basaltic network, and basaltic compute instances list is
basaltic compute instance list. The forms below are the ones to write.
A service with a single resource of the same name drops the middle word:
basaltic certificate list, not basaltic certificate certificate list.
basaltic --help lists the services; basaltic <service> --help and
basaltic <service> <resource> --help walk down from there.
Authenticating
Region discovery works before you sign in:~/.config/basaltic/config.yaml. Tokens do
not: they are written to ~/.config/basaltic/credentials.yaml, mode 0600, so a
config file stays safe to copy between machines or check into dotfiles.
basaltic login signs you in as a person — it prints a URL where you
approve the CLI and pick an organization, shows you a code to paste back in the
terminal, and stores a short-lived token that acts as you. That is what lets you
create an organization, accept an invitation or switch org from the CLI; a
service account cannot do any of those. The browser does not have to be on the
same machine, so this works over SSH. See
signing in as yourself.
Workspace commands manage organization resources, such as users, groups,
accounts, and organization policies. IAM commands manage roles, service
accounts, policies, and sessions in the selected account. These are separate
policy domains even though both services are global.
A personal login does not automatically grant account resource access to a
person, including the organization owner. Use an assigned role and the AssumeRole API for account work.
Changing a profile’s account alone cannot change a credential’s account scope.
See account access.
For a program that has to run without you, use an access key from a
service account instead:
Output
--output text is the default and prints tables. --output json and
--output yaml print the API’s own field names, for piping.
Paging
List commands return one page and say when there is more.--all walks every
page:
Creating things
Scalar fields are flags. Anything structured takes JSON, because a nested object has no honest flat representation:--from-file takes the whole body as JSON or YAML, and
flags override individual fields of it:
networks among them — and the flags
beside it override individual keys.
Retrying a create
A create that times out may already have succeeded, so the CLI will not repeat one on its own. Give it a key and it becomes safe to retry — the platform returns the original outcome instead of building a second resource:Global flags
--output json is the one to reach for in scripts.
--account-id is required to reach another account you are authorized for.
Without it, that account’s resources answer “not found” rather than “not
permitted” — an account you are not acting in is one whose resources you
cannot see.BASALTIC_API_KEY,
BASALTIC_REGION, BASALTIC_ACCOUNT_ID, BASALTIC_PROFILE. A flag overrides
both.
Configuration
region, api_key, account_id and domain. Use --profile to
write to a profile other than the active one:
~/.config/basaltic/, honoring XDG_CONFIG_HOME.
Serial console
Ctrl-C, which is usually what you want it
for. Press Ctrl-] to disconnect.
That is a live terminal, not a log. For what the instance has already printed: