> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Go SDK: manage applications

> Fetch, inspect and control your applications with the Go SDK: details, status, start, stop, restart, logs, metrics, domains, load balancers and deletion.

Every method on this page lives on `c.Apps` and takes `ctx` first, then the app id. An `appID` can also be the composite `<appId>-<workspaceId>` of an app shared through a [workspace](/en/sdks/go/workspaces).

Each snippet below runs on its own inside this program: paste one at a time into `main` and run `goimports` (see [Running the examples](/en/sdks/go/client#running-the-examples)).

```go theme={"system"}
package main

import (
	"context"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

var (
	ctx   = context.Background()
	c     = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))
	appID = "abc123def456abc123def456"
)

func main() {
	// Paste one snippet here, then run goimports.
}
```

To list your apps, use [`c.Account.Me`](/en/sdks/go/client#account): its `Applications` slice has every app the key can see.

## Getting an application

```go theme={"system"}
app, err := c.Apps.Get(ctx, appID)
if err != nil {
	log.Fatal(err)
}

fmt.Println(app.ID, app.Name, app.Language, app.RAM, app.Cluster, app.CreatedAt)
```

| Field | Type | Description |
| - | - | - |
| `ID` (`id`) | `string` | App id |
| `Name` (`name`) | `string` | Display name |
| `Description` (`desc`) | `string` | Description, `""` when unset |
| `Owner` (`owner`) | `string` | Owner's user id |
| `Cluster` (`cluster`) | `string` | Cluster the app runs on |
| `RAM` (`ram`) | `int` | Allocated RAM in MB |
| `Language` (`language`) | `string` | Runtime language |
| `Domain` (`domain`) | `*string` | Default `<subdomain>.squareweb.app` host; `nil` for non-web apps |
| `Custom` (`custom`) | `*string` | Custom domain; `nil` when none is set |
| `CreatedAt` (`created_at`) | `time.Time` | Creation date |

## Status

`Status(ctx, appID)` returns the live state with **formatted** values:

```go theme={"system"}
status, err := c.Apps.Status(ctx, appID)
if err != nil {
	log.Fatal(err)
}

fmt.Println(status.Status)  // e.g. "running", "exited"
fmt.Println(status.Running) // true
fmt.Println(status.CPU)     // "0.5%"
fmt.Println(status.RAM)     // "120.4MB" (RAM in use)
fmt.Println(status.Storage, status.Network.Total, status.Network.Now)
if status.Uptime != nil {
	fmt.Println(*status.Uptime) // Unix ms of the last start; nil when stopped
}
```

`StatusRaw(ctx, appID)` returns **numbers** instead (`CPU` in %, `RAM` in MB, `Storage` in bytes, `Network.Total` and `Network.Now` as `[in, out]` byte pairs):

```go theme={"system"}
raw, err := c.Apps.StatusRaw(ctx, appID)
if err != nil {
	log.Fatal(err)
}

fmt.Println(raw.CPU, raw.RAM, raw.Network.Total) // 0.5 120.4 [1024 2048]
```

<Note>
  `Uptime` is a **timestamp** (when the app started), not a duration. Use `time.Since(time.UnixMilli(*status.Uptime))` for how long it has been up.
</Note>

### Status of every application

`StatusAll(ctx, workspaceID)` returns one summary per app the key can see, in a single request. Pass `""` for all apps, or a workspace id for the apps of that [workspace](/en/sdks/go/workspaces#acting-on-a-shared-app) only. `CPU` and `RAM` are only set (not `""`) while the app runs.

```go theme={"system"}
items, err := c.Apps.StatusAll(ctx, "")
if err != nil {
	log.Fatal(err)
}
for _, it := range items {
	if it.Running {
		fmt.Println(it.ID, it.CPU, it.RAM)
	} else {
		fmt.Println(it.ID, "stopped")
	}
}
```

## Start, stop and restart

```go theme={"system"}
if err := c.Apps.Start(ctx, appID); err != nil {
	log.Fatal(err)
}
if err := c.Apps.Stop(ctx, appID); err != nil {
	log.Fatal(err)
}
if err := c.Apps.Restart(ctx, appID); err != nil {
	log.Fatal(err)
}
```

The server holds these calls open until the container acts, so without a `ctx` deadline they wait at least 2 minutes before timing out. When the platform refuses the action, the call returns an `*APIError` with status **409**, a `Code` and an **empty** `Message`:

| Code | Meaning |
| - | - |
| `CONTAINER_ALREADY_STARTED` | `start` on a running app |
| `CONTAINER_ALREADY_STOPPED` | `stop` on a stopped app |
| `CONTAINER_TEMPORARILY_SUSPENDED` | The app is suspended |
| `CONTAINER_NOT_FOUND` | The container does not exist on the cluster |
| `CONTAINER_INSUFFICIENT_DISK_SPACE` | Not enough disk to start |
| `CONTAINER_NETWORK_CONFLICT` | Network conflict on the cluster |
| `ACTION_FAILED` | The cluster could not perform the action |

"Already started" and "already stopped" are errors too. If they mean success for you, handle them:

```go theme={"system"}
err := c.Apps.Start(ctx, appID)

var apiErr *squarecloud.APIError
if err != nil && !(errors.As(err, &apiErr) && apiErr.Code == squarecloud.CodeContainerAlreadyStarted) {
	log.Fatal(err)
}
```

## Logs

`Logs(ctx, appID)` returns the latest console output as one string (`""` when there is none).

```go theme={"system"}
logs, err := c.Apps.Logs(ctx, appID)
if err != nil {
	log.Fatal(err)
}
fmt.Println(logs)
```

For a live stream of logs, use [Realtime](/en/sdks/go/realtime).

## Metrics

`Metrics(ctx, appID)` returns the last 24 hours, one point every 5 minutes, **newest first**.

```go theme={"system"}
points, err := c.Apps.Metrics(ctx, appID)
if err != nil {
	log.Fatal(err)
}
if len(points) > 0 {
	latest := points[0]
	fmt.Println(latest.Date, latest.CPU, latest.RAM, latest.Net)
}
```

## Domains and load balancers

`Domains(ctx)` lists the default and custom hostnames of every app. `LoadBalancers(ctx)` lists the domains shared by several apps, with your plan's limit.

```go theme={"system"}
domains, err := c.Apps.Domains(ctx)
if err != nil {
	log.Fatal(err)
}
for _, d := range domains {
	fmt.Println(d.AppID, d.Hostname, d.Type) // Type: "subdomain" | "custom"
}

lb, err := c.Apps.LoadBalancers(ctx)
if err != nil {
	log.Fatal(err)
}
fmt.Println(lb.Limit)
for _, balancer := range lb.Balancers {
	ids := make([]string, 0, len(balancer.Apps))
	for _, app := range balancer.Apps {
		ids = append(ids, app.ID)
	}
	fmt.Println(balancer.Hostname, ids)
}
```

To set a custom domain, see [Network](/en/sdks/go/network#custom-domain).

## Deleting an application

```go theme={"system"}
if err := c.Apps.Delete(ctx, appID); err != nil {
	log.Fatal(err)
}
```

<Warning>
  Deletion is permanent. Create a [snapshot](/en/sdks/go/snapshots) first if you may need the files again.
</Warning>

## Next steps

<CardGroup cols={3}>
  <Card title="Commit and upload" icon="upload" href="/en/sdks/go/commit_and_upload">
    Create an app from a zip or send files to one.
  </Card>

  <Card title="Application API reference" icon="code" href="/en/api-reference/endpoint/apps/info">
    The REST endpoints behind these methods.
  </Card>

  <Card title="Manage apps from the CLI" icon="terminal" href="/en/cli-reference/apps">
    The same actions from the terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.