logs

1ctl logs gives you two ways to read your application’s output: a snapshot of recent lines stored in the database, and a live stream proxied directly from the Kubernetes pod log stream via WebSocket.

you → 1ctl logs        → GET  /v1/cli/loki/logs/{id}                → database snapshot
you → 1ctl logs stream → WebSocket /v1/pods/stream/logs/{ns}/{app}  → live pod stream

Stored logs are available immediately after a deployment starts and persist for as long as the deployment exists. The live stream requires at least one running pod — if the deployment is scaled to zero or still pending, the WebSocket connection will close with an error.

Implemented. 1ctl logs supports --tail. 1ctl logs stream does not support --tail; use --batch-size to tune streaming batch size.

Commands

1ctl logs

1ctl logs [--deployment-id <id>] [--config <cfg>] [-n/--tail <lines>]

Fetches recent log lines from the database snapshot. Satusky writes pod output into the deployment_logs table in PostgreSQL on a rolling basis, so this command returns quickly without a live connection to the cluster.

Flags

Flag	Short	Default	Description
--deployment-id <id>		satusky.toml	Deployment to fetch logs for. If omitted, resolved from satusky.toml in the current directory.
--tail <lines>	-n	100	Number of lines to return, counted from the most recent.
--config <name>		satusky.toml	Named config file to use (e.g. staging resolves to satusky.staging.toml).

Under the hood:

1. 1ctl resolves the deployment ID from the flag or from satusky.toml
2. GET /v1/cli/loki/logs/{deploymentID} — the ?tail=N query parameter controls how many lines the API reads from the stored log source
3. The API returns the lines as a JSON array; 1ctl prints them to stdout in order

Examples

# View the last 100 lines for the project in the current directory
1ctl logs

# Limit to the last 50 lines
1ctl logs --tail 50

# Fetch logs for a specific deployment by ID
1ctl logs --deployment-id cb7db400-392f-465b-8c05-829d1008f3ed --tail 20

# Use a named environment config
1ctl logs --config staging

---

1ctl logs stream

1ctl logs stream [--deployment-id <id>] [-n/--namespace <ns>] [-a/--app <label>] [--batch-size <n>] [--config <cfg>]

Opens a persistent WebSocket connection to the Satusky backend, which proxies the Kubernetes pod log stream in real time. The connection stays open until you press Ctrl+C or the server closes the stream.

Flags

Flag	Short	Default	Description
--deployment-id <id>		satusky.toml	Deployment to stream logs for. If omitted, resolved from satusky.toml.
--namespace <ns>	-n	active org namespace	Kubernetes namespace to target. Rarely needed — your org namespace is used automatically.
--app <label>	-a	app name from satusky.toml	Kubernetes app label to filter pods by.
--batch-size <n>		100	Number of log lines the server sends per WebSocket message. Lower values reduce buffering latency.
--config <name>		satusky.toml	Named config file to use.

Under the hood:

1. 1ctl opens a WebSocket to /v1/pods/stream/logs/{namespace}/{appLabel} and sends x-satusky-api-key in the upgrade headers
2. The backend identifies the matching pods in the target namespace and opens a multiplexed Kubernetes log stream against each running pod
3. Log lines are batched (controlled by --batch-size) and sent as WebSocket frames to the CLI
4. 1ctl reads each frame and writes the lines to stdout as they arrive
5. If Loki is configured in your cluster, the backend also indexes lines there for longer-term retention — the stream itself is unaffected either way

Examples

# Stream live logs for the project in the current directory
1ctl logs stream

# Stream logs for a specific deployment
1ctl logs stream --deployment-id cb7db400-392f-465b-8c05-829d1008f3ed

# Reduce batch size for lower-latency output
1ctl logs stream --batch-size 10

# Stream from a staging config
1ctl logs stream --config staging

Log retention

Stored logs (the 1ctl logs snapshot) reflect what was most recently written to the deployment_logs table. This is a rolling buffer — older lines are evicted as new ones arrive. For longer retention, configure Loki in your cluster settings; when Loki is enabled, every line ingested by the streaming backend is also indexed and queryable outside 1ctl.

Deployment ID resolution

Both subcommands resolve the target deployment the same way (first match wins):

1. --deployment-id flag
2. deployment_id field in satusky.toml (or the file named by --config)
3. Error — no deployment can be identified

v1 target

The CLI should print how it resolved the target when ambiguity is possible:

Streaming logs for orgv1-80c8588b/diagnosis-bot
Resolved from deployment ID cb7db400-392f-465b-8c05-829d1008f3ed

This matters in CI and multi-profile workflows where the same app name can exist in more than one namespace or API profile.