For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/web/terminal-basics.md (or send Accept: text/markdown).
Commands, files and configuration
Learn where to paste commands, how to open the correct project folder, edit .env files, stop a server and report a setup error without sharing secrets.
A command goes in the terminal
A terminal is the window where you type instructions for your computer. In Visual Studio Code, first open your supastack folder using File → Open Folder, then select Terminal → New Terminal. The new terminal starts in that folder. On Windows choose PowerShell using the menu next to the terminal's + button. Use macOS/Linux blocks in a macOS or Linux terminal.
Paste only the contents of a command block, one command at a time, and press Enter. Do not paste the surrounding Markdown backticks, a prompt such as PS C:\..., or example output. Lines starting with # are explanations; they do not run anything. Wait for each installation command to finish before entering the next command. A server command keeps running and does not return a fresh prompt until you stop it.
Check which folder the terminal is using
Repository root means the top-level supastack folder containing package.json, pnpm-workspace.yaml, apps and packages. Unless a step says otherwise, run commands there. The command below prints the current folder; the file listing should show package.json. In Windows PowerShell pwd and ls also work.
If the listing shows only the contents of apps/web or apps/mobile, type cd ../.. and press Enter to return to the root. If it shows your home folder, type cd followed by a space and the full path to your clone, enclosed in quotation marks when it contains spaces. Opening the project folder in the editor and creating a new terminal is usually easier.
pwd
lsConfiguration goes in a file, not in the terminal
A block like AI_PROVIDER=fake is configuration text. Open the named .env file in the editor, find the line beginning AI_PROVIDER=, replace its value and save with Ctrl + S (Command + S on macOS). Each setting occupies one line in KEY=value form. Do not add Markdown backticks. Avoid duplicate copies of the same key in one file.
Use root .env for database migration commands, apps/web/.env.local for the Next.js Web server, and apps/mobile/.env.local for Expo. Next and Expo run inside their own app folders and do not automatically load root .env. If a database connection changes, update DATABASE_URL in both root .env and apps/web/.env.local so migrations and the server use the same database. Keep the example file unchanged for future reference.
Files whose names start with a dot may be hidden in your file manager; the editor's Explorer shows them. Make sure the filename is exactly .env.local, not .env.local.txt. These local files can contain passwords and are excluded from Git; do not upload them or paste their contents into support messages.
Keep the server running; use another terminal for commands
The development server serves your app while you work. Leave its terminal open when a tutorial says open localhost:3000. localhost means this computer; :3000 is the port, like a numbered door used by the app. Put the URL into your browser's address bar, not the terminal.
To run another command while the server is active, select Terminal → New Terminal in the editor. The new terminal is a separate window into the same project. To stop the server, select its terminal and press Ctrl + C once. On Windows, if asked Terminate batch job, type Y and press Enter. Wait for the normal prompt before starting it again.
After editing Web environment settings, stop and restart the Web server with the command below. Saving a source file normally refreshes the page automatically, but environment changes need a restart. After editing Expo settings, stop Expo, then run corepack pnpm --filter @supastack/mobile start --clear to restart and clear its cached bundle.
corepack pnpm --filter @supastack/web devRead a failure and ask for useful help
If an installation returns red error text, stop at that step. Read the first error rather than continuing to launch the app. Command not found usually means a missing tool; no package.json usually means the wrong folder; ECONNREFUSED usually means a required server or database is not running; EADDRINUSE means another process already uses the port.
When asking for help, include your operating system, the guide URL and step number, the exact command you entered, and the first error message. Remove passwords, API keys, tokens and the password portion of any database URL. Do not send your .env files. A screenshot of the error can help, but copyable text is easier to diagnose.