CLI Overview

1ctl is the official command-line interface for Satusky. It is a thin HTTP client — every command translates to one or more calls to the Satusky API at https://api.satusky.com/v1/cli. The actual work (building images, scheduling pods, issuing certificates) happens server-side on your cluster. 1ctl never needs Docker or kubectl installed locally.

you → 1ctl deploy → POST /v1/cli/deployments → Satusky API → Kubernetes

For the operational contract behind the CLI, including current gaps and v1 target behavior, see 1ctl v1 Contract. This overview describes the command surface and mechanics.

Global flags

These flags are accepted by every command.

Flag	Short	Default	Description
--profile	-p	active profile	Named configuration profile to use for this command. Not persisted.
--api-url		active profile URL	Override the API base URL for this command only.
--output	-o	table	Output format: table or json.

API URL resolution order

When a command runs, 1ctl resolves which API URL to call using this priority chain (first match wins):

1. --api-url flag
2. SATUSKY_API_URL environment variable
3. URL stored in the active profile
4. Default: https://api.satusky.com

Output formats

--output table is the default. It produces aligned, human-readable output designed for terminals.

--output json prints a JSON object or array to stdout. Use it to pipe into jq, feed CI scripts, or capture structured data.

# Get your deployments as JSON and extract names
1ctl -o json deploy list | jq '.[].app_label'

--output is a global flag. Put it before the command group for the most reliable behavior:

1ctl -o json deploy get --deployment-id <id>

Some subcommands do not accept global flags after the subcommand, so prefer 1ctl -o json ... over 1ctl deploy list -o json.

Environment variable overrides

You can drive 1ctl entirely through environment variables — useful in CI where writing config files is inconvenient.

Variable	Equivalent flag / behaviour
SATUSKY_API_KEY	Authenticates all requests. Skips reading ~/.satusky/context.json.
SATUSKY_API_URL	Sets the API base URL (second in resolution order).
SATUSKY_PROFILE	Sets the active profile by name.

The satusky.toml config file

satusky.toml is the per-project config file created by 1ctl init. It lives in the root of your repository and is the source of truth for what 1ctl deploy sends to the API.

[app]
  name       = "my-app"
  port       = 8080
  cpu        = "0.5"
  memory     = "256Mi"
  dockerfile = "Dockerfile"
  replicas   = 1

Field	Type	Description
name	string	App label used to identify the deployment in Kubernetes. Must be unique within your namespace.
port	integer	Container port your application listens on.
cpu	string	Kubernetes CPU request (e.g. "0.5" = 500m).
memory	string	Kubernetes memory request (e.g. "256Mi", "1Gi").
dockerfile	string	Path to the Dockerfile, relative to project root.
replicas	integer	Initial replica count.

You can maintain multiple config files for different environments by naming them satusky.staging.toml, satusky.production.toml, and so on. Pass them to any command with --config <name>:

1ctl deploy --config staging

Profile system

A profile is a named set of connection settings: an API URL and an authentication token. Profiles are stored in ~/.satusky/profiles.json. The active profile is tracked in ~/.satusky/context.json.

Before every command (except auth, profile, completion, and version) the CLI reads the active profile, loads its token, and validates it against the API. If the token is missing or expired the command fails with an authentication error.

Use profiles to keep separate configurations for different Satusky environments or different accounts without clobbering your credentials between contexts:

1ctl profile create --url https://dev-api.satusky.com dev
1ctl profile create --url https://api.satusky.com    prod

1ctl profile use dev
1ctl deploy          # hits dev-api.satusky.com

1ctl --profile prod deploy   # one-off override, not persisted

Auth state files

File	Contents
~/.satusky/context.json	Active token, user_id, org_id, email, active profile name.
~/.satusky/profiles.json	All named profiles with their API URLs and auth status.

Command groups

Command	What it manages
auth	Login, logout, and token status
profile	Named connection profiles
init	Project config file (satusky.toml)
launch	Interactive project detection and config generation
deploy	Container deployments
logs	Runtime log streaming
secret	Encrypted secret values
env	Plain environment variables
domains, domain	Custom and platform domain records
machine	Owned machines, available machines, and usage records
org	Organisation management
marketplace	One-click app installations
credits, billing	Credit balance and billing state
token, api-token	API token management
user	User account settings
audit	Audit log queries
notifications, notif	Notification preferences and history
cluster	Cluster and zone information
pricing	Resource pricing lookups
completion	Shell completion generation

Some documentation pages describe platform or legacy concepts such as direct Service, Ingress, Issuer, object storage, Talos, or admin operations. Treat a page as current CLI reference only when the command appears in your installed 1ctl --help.

Backend

All CLI routes live under /v1/cli/* on the API server. Every request must carry a valid API key in the x-satusky-api-key header. The API validates the key against the api_tokens table before any handler logic runs — there is no separate session cookie or JWT flow for CLI usage.