> ## 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.

# Gerenciando aplicações

> Inspecione, controle e opere uma aplicação através da classe Application — status, logs, métricas, ciclo de vida (start, stop, restart) e exclusão.

Todas as operações desta página começam obtendo uma instância de `Application`:

```typescript theme={null}
import { SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARE_API_KEY!);
const app = await api.applications.fetch("abc123def456abc123def456");
```

`api.applications.fetch(id)` retorna uma `Application`. Quando a aplicação possui um domínio web, ela é retornada como `WebsiteApplication` — refine o tipo em tempo de execução com `app.isWebsite()` antes de usar `.network` (veja [Rede](/pt-br/sdks/js/network)).

## Propriedades da aplicação

| Propriedade   | Tipo             | Descrição                                                                                                         |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `id`          | `string`         | ID da aplicação (24 chars hex)                                                                                    |
| `name`        | `string`         | Nome de exibição                                                                                                  |
| `description` | `string?`        | Descrição vinda do `squarecloud.app`                                                                              |
| `url`         | `string`         | URL do dashboard web                                                                                              |
| `ram`         | `number`         | RAM alocada em MB                                                                                                 |
| `cluster`     | `string`         | Cluster onde a aplicação roda                                                                                     |
| `language`    | `string`         | `javascript` \| `typescript` \| `python` \| `java` \| `elixir` \| `rust` \| `go` \| `php` \| `dotnet` \| `static` |
| `domain`      | `string \| null` | Host padrão `<subdominio>.squareweb.app` (`null` para apps não-web)                                               |
| `custom`      | `string \| null` | Domínio customizado vinculado à aplicação, se configurado                                                         |
| `createdAt`   | `Date`           | Data de criação                                                                                                   |

<Note>
  Na v4, `app.custom` é `null` quando nenhum domínio customizado está configurado (era `undefined` na v3).
</Note>

## Obtendo o status da aplicação

`app.getStatus()` retorna uma instância de `ApplicationStatus` com o estado de execução em tempo real.

```typescript theme={null}
const status = await app.getStatus();

console.log(status.status);          // "running" | "starting" | "restarting" | "exited" | "created" | "deleting"
console.log(status.running);         // boolean
console.log(status.usage.cpu);       // "0,22%"
console.log(status.usage.ram);       // "70MB"
console.log(status.usage.network);   // { total: "0 KB ↑ 0 KB ↓", now: "0 KB ↑ 0 KB ↓" }
console.log(status.usage.storage);   // "0B"
console.log(status.uptime);          // Date | undefined
console.log(status.uptimeTimestamp); // number | undefined
```

### Status resumido para todas as aplicações

Para evitar uma requisição por aplicação, use `api.applications.statusAll()`:

```typescript theme={null}
const list = await api.applications.statusAll();

for (const summary of list) {
    console.log(`${summary.applicationId} → running=${summary.running}`);
    if (summary.running) {
        console.log(`  cpu=${summary.usage.cpu}, ram=${summary.usage.ram}`);
    }

    // Promova o resumo para o status completo com .fetch()
    const full = await summary.fetch();
    console.log(full.uptime);
}
```

## Obtendo os logs

`app.getLogs()` retorna a saída de log mais recente como `string`.

```typescript theme={null}
const logs = await app.getLogs();
console.log(logs);
```

## Obtendo métricas

`app.getMetrics()` retorna as últimas 24 horas de amostras de CPU, RAM e rede (até **288 pontos**, um a cada 5 minutos).

```typescript theme={null}
const metrics = await app.getMetrics();

console.log(metrics.length, "pontos");
console.log(metrics[0]);
// { timestamp: 1717084800000, cpu: 12.3, ram: 187, network: { ... } }
```

<Warning>
  `getMetrics()` exige que a aplicação tenha **no mínimo 512MB de RAM** alocados.
</Warning>

## Stream de eventos em tempo real

`app.realtime()` abre um stream [Server-Sent Events](https://developer.mozilla.org/docs/Web/API/Server-sent_events). Veja a página dedicada de [Tempo real](/pt-br/sdks/js/realtime) para um exemplo completo.

## Ciclo de vida

Todos os métodos de ciclo de vida resolvem para `boolean` (`true` em caso de sucesso).

```typescript theme={null}
await app.start();
await app.restart();
await app.stop();
```

## Excluindo uma aplicação

<Warning>
  `app.delete()` remove a aplicação permanentemente. Sem um [snapshot](/pt-br/sdks/js/snapshots), os dados **não podem ser recuperados**.
</Warning>

```typescript theme={null}
const deleted = await app.delete();
console.log(deleted); // true | false
```

## Atualizando os dados da aplicação

`app.fetch()` rebusca a aplicação na API e retorna uma nova instância de `Application`. Use quando suspeitar que os dados em cache estão desatualizados.

```typescript theme={null}
const fresh = await app.fetch();
```