> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Comandos, arquivos e configuração

Aprenda onde colar comandos, como abrir a pasta correta do projeto, editar arquivos .env, parar um servidor e reportar um erro de configuração sem compartilhar segredos.

## Um comando vai no terminal

Um terminal é a janela onde você digita instruções para o seu computador. Em Visual Studio Code, primeiro abra sua pasta supastack usando Arquivo → Abrir pasta e selecione Terminal → Novo Terminal. O novo terminal começa nessa pasta. No Windows escolha PowerShell usando o menu próximo ao botão + do terminal. Use blocos macOS/Linux em um terminal macOS ou Linux.

Cole apenas o conteúdo de um bloco de comando, um comando por vez, e pressione Enter. Não cole os crases do Markdown ao redor, um prompt como PS C:\... ou uma saída de exemplo. As linhas que começam com # são explicações; eles não executam nada. Aguarde a conclusão de cada comando de instalação antes de inserir o próximo comando. Um comando do servidor continua em execução e não retorna um novo prompt até que você o interrompa.


## Verifique qual pasta o terminal está usando

Raiz do repositório significa a pasta supastack de nível superior contendo package.json, pnpm-workspace.yaml, aplicativos e pacotes. A menos que uma etapa indique o contrário, execute comandos lá. O comando abaixo imprime a pasta atual; a listagem de arquivos deve mostrar package.json. No Windows PowerShell pwd e ls também funcionam.

Se a listagem mostrar apenas o conteúdo de apps/web ou apps/mobile, digite cd ../.. e pressione Enter para retornar à raiz. Se mostrar sua pasta pessoal, digite cd seguido de um espaço e o caminho completo para seu clone, entre aspas quando contiver espaços. Abrir a pasta do projeto no editor e criar um novo terminal geralmente é mais fácil.

```
pwd
ls
```


## A configuração vai em um arquivo, não no terminal

Um bloco como AI_PROVIDER=fake é um texto de configuração. Abra o arquivo .env nomeado no editor, encontre a linha que começa com AI_PROVIDER=, substitua seu valor e salve com Ctrl + S (Command + S no macOS). Cada configuração ocupa uma linha no formato KEY=value. Não adicione crases Markdown. Evite cópias duplicadas da mesma chave em um arquivo.

Use root .env para comandos de migração de banco de dados, apps/web/.env.local para o servidor Web Next.js e apps/mobile/.env.local para Expo. Next e Expo são executados dentro de suas próprias pastas de aplicativos e não carregam automaticamente o root .env. Se uma conexão de banco de dados for alterada, atualize DATABASE_URL em root .env e apps/web/.env.local para que as migrações e o servidor usem o mesmo banco de dados. Mantenha o arquivo de exemplo inalterado para referência futura.

Arquivos cujos nomes começam com um ponto podem estar ocultos no seu gerenciador de arquivos; o Explorer do editor os mostra. Certifique-se de que o nome do arquivo seja exatamente .env.local, não .env.local.txt. Esses arquivos locais podem conter senhas e são excluídos do Git; não os carregue nem cole seu conteúdo em mensagens de suporte.

[Encontre o significado de cada configuração](https://supastack.dev/pt/docs/web/project-structure.md)


## Mantenha o servidor funcionando; use outro terminal para comandos

O servidor de desenvolvimento atende seu aplicativo enquanto você trabalha. Deixe seu terminal aberto quando um tutorial disser aberto localhost:3000. localhost significa este computador; :3000 é a porta, como uma porta numerada usada pelo aplicativo. Coloque URL na barra de endereço do seu navegador, não no terminal.

Para executar outro comando enquanto o servidor estiver ativo, selecione Terminal → Novo Terminal no editor. O novo terminal é uma janela separada no mesmo projeto. Para parar o servidor, selecione seu terminal e pressione Ctrl + C uma vez. No Windows, se for solicitado Encerrar trabalho em lote, digite Y e pressione Enter. Aguarde o prompt normal antes de iniciá-lo novamente.

Após editar as configurações do ambiente Web, pare e reinicie o servidor Web com o comando abaixo. Salvar um arquivo de origem normalmente atualiza a página automaticamente, mas as alterações de ambiente precisam ser reiniciadas. Após editar as configurações de Expo, pare Expo e execute corepack pnpm --filter @supastack/mobile start --clear para reiniciar e limpar seu pacote em cache.

```
corepack pnpm --filter @supastack/web dev
```


## Leia uma falha e peça ajuda útil

Se uma instalação retornar um texto de erro em vermelho, pare nessa etapa. Leia o primeiro erro em vez de continuar a iniciar o aplicativo. Comando não encontrado geralmente significa uma ferramenta ausente; nenhum package.json geralmente significa a pasta errada; ECONNREFUSED geralmente significa que um servidor ou banco de dados necessário não está em execução; EADDRINUSE significa que outro processo já usa a porta.

Ao pedir ajuda, inclua seu sistema operacional, o guia URL e o número da etapa, o comando exato que você digitou e a primeira mensagem de erro. Remova senhas, chaves API, tokens e a parte da senha de qualquer banco de dados URL. Não envie seus arquivos .env. Uma captura de tela do erro pode ajudar, mas o texto copiável é mais fácil de diagnosticar.

[Solucionar uma falha de configuração específica](https://supastack.dev/pt/docs/web/troubleshooting.md)


## Seguinte

[Deixe um agente fazer a configuração](https://supastack.dev/pt/docs/web/agent-setup.md)