Automation CLI (`skyportalai`)

Use skyportalai for stable automation in scripts and CI/CD.

Tip

Put global options before the subcommand.

Syntax

skyportalai [--json] [--base-url URL] [--version] COMMAND

Option	Behavior
`--json`	Emit a stable JSON envelope
`--base-url URL`	Override API target for this invocation
`--version`	Print installed version and exit
`--help`	Show command help

Configuration commands

Show effective settings

skyportalai config show
skyportalai --json config show

Reports API target, timeout, auth state, credential source, and config path. It never prints credential values.

Save connection settings

skyportalai config set --base-url https://app.skyportal.ai
skyportalai config set --timeout 30
skyportalai config set --base-url https://app.skyportal.ai --timeout 30

At least one option is required.
--timeout must be greater than zero.
This command does not write secret credentials.

Chat commands

Start a chat

skyportalai chat send \
  "Report disk usage and identify the largest directory" \
  --server 42 \
  --wait

skyportalai chat send MESSAGE
  [--server ID]
  [--chat-id ID]
  [--wait]
  [--timeout SECONDS]
  [--poll-interval SECONDS]

--server ID targets a server for new chat creation.
--chat-id ID sends to an existing chat.
--server and --chat-id cannot be used together.
--wait polls until settled or awaiting approval.
--timeout default: 300, must be greater than zero.
--poll-interval default: 1, must be zero or greater.

Continue a chat

skyportalai chat send \
  "Now inspect the previous job logs" \
  --chat-id 123 \
  --wait

Status, messages, and waiting

skyportalai chat status 123
skyportalai chat messages 123
skyportalai chat messages 123 --after-sequence 40 --limit 100
skyportalai chat wait 123 --timeout 300 --poll-interval 1

messages pagination:

--after-sequence default: 0, must be zero or greater.
--limit default: 100, valid range: 1 to 500.

Approve an action

Always review status first, then approve the exact reviewed action:

skyportalai --json chat status 123

skyportalai chat approve \
  123 APPROVAL_ID \
  --type bash_command \
  --command "EXACT REVIEWED COMMAND"

Approval type defaults to bash_command; plan is supported when requested by the server.

Reject an action

skyportalai chat reject \
  123 APPROVAL_ID \
  --type bash_command \
  --reason "Outside the approved scope"

Cancel an active workflow

skyportalai chat cancel 123
skyportalai chat cancel 123 --reason "No longer required"

The server may return a conflict if the workflow is already idle.

JSON mode

Place --json before the subcommand:

skyportalai --json chat send \
  "Check API connectivity" \
  --server 42 \
  --wait

Success envelope:

{
  "ok": true,
  "api_target": "https://app.skyportal.ai",
  "data": {}
}

Expected failure envelope (stderr):

{
  "ok": false,
  "api_target": "https://app.skyportal.ai",
  "error": "Error message"
}

Exit codes

Code	Meaning
`0`	Success
`1`	Configuration, authentication, connection, API, or workflow error
`2`	Awaiting approval, missing args, conflicting options, or validation/usage error

Info

Exit code 2 with status: "awaiting_approval" is an expected human-decision stop, not an API failure.

Security

Use placeholders in scripts and docs.
Never auto-approve destructive actions.
Never log real credentials or private infrastructure identifiers.
Prefer --json in automation for deterministic parsing.

Automation CLI (skyportalai)