Files, Terminals, Commands, Packages, and Environment Variables
You do not need to memorize terminal commands to supervise an agent. You need a mental model of where a command runs, what it reads, what it changes, and how to check the result.
Files and folders
A path is an address. An absolute path begins from the filesystem root; a relative path begins from the current folder. In documentation, ./ means “here” and ../ means “the parent folder.”
Projects commonly contain:
- Source files you edit, such as
.ts,.tsx,.py,.css, and.md. - Configuration such as
package.json,tsconfig.json, andpyproject.toml. - Lockfiles that record exact dependency versions.
- Generated folders such as
node_modules, build outputs, and caches. - Environment files such as
.env.local, which may contain secrets and must not be committed.
Capitalization matters on many systems. Transaction.tsx and transaction.tsx may be different files.
The current working directory
The terminal always has a current folder. Commands act there unless given another path.
pwd
lspwd prints the current directory on Unix-like shells. ls lists entries. PowerShell alternatives include Get-Location and Get-ChildItem.
Move deliberately:
cd expense-dashboardBefore approving any command that creates, deletes, initializes, or installs, confirm the current path. Initializing a framework in the wrong folder can scatter hundreds of files.
Commands, flags, and arguments
In npm run dev, npm is the program, run is a subcommand, and dev names a script. In git status --short, --short is a flag that changes output format.
Risk grows when commands:
- Recursively delete or overwrite.
- Run with administrator privileges.
- Download and immediately execute code.
- Change global configuration.
- Target a broad path or unresolved wildcard.
- Apply database migrations or deploy production resources.
Ask the agent to explain the program, target, expected files, reversibility, and verification before approval.
Processes and servers
npm run dev starts a long-running development process. The terminal appears busy because the server keeps listening for requests. Usually Ctrl+C stops it.
A local URL such as http://localhost:3000 is reachable on your computer. It is not automatically public. A port is a numbered channel used by a process; two processes cannot usually bind the same port simultaneously.
Read server output from the bottom upward. The final error and the first relevant stack frame often matter more than a wall of warnings.
Packages and dependencies
A package is reusable code maintained separately from your project. npm installs JavaScript packages described in package.json; Python tools install packages described in pyproject.toml.
Dependencies add capability and risk. Before approving one, check:
- Is it actually needed?
- Is it official or reputable and maintained?
- Does it support the installed framework version?
- What permissions or native configuration does it require?
- Does the license fit your project?
Commit the manifest and lockfile. Do not commit node_modules or a Python virtual environment.
JSON and YAML
JSON configuration uses quoted keys, colons, commas, braces, and brackets. A missing comma can stop the entire file from loading. YAML uses indentation and is sensitive to spacing.
Do not “fix” configuration by guessing. Paste the exact parser error and ask the agent to inspect the relevant file and schema.
Environment variables
Environment variables provide values outside source code. Typical names include:
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
DATABASE_URL=Prefixes such as NEXT_PUBLIC_ or EXPO_PUBLIC_ intentionally expose values to client code. A value is not secret merely because it lives in .env; if client code uses it, users can inspect it. Only provider-designated publishable keys belong there. Service-role keys, database passwords, signing secrets, and private API keys remain server-only.
Commit .env.example with empty placeholders and documentation. Add real environment files to .gitignore. If a secret enters Git history or a chat, rotate it; deleting the visible line is not enough.
Read an error systematically
Capture:
- The command you ran.
- The current directory.
- The complete error text.
- What you expected.
- The last known change.
Then ask:
Diagnose this error without editing yet. Separate facts from hypotheses.
Identify the first relevant error, the likely layer, and the smallest read-only
checks that can confirm the cause. Do not reinstall everything or delete caches
unless evidence shows that is necessary.
Command: [...]
Expected: [...]
Error: [...]Safe practice exercise
In a disposable folder, create notes.md through your editor. Ask the agent to list the folder, display Git status, and explain each command. Then initialize Git and inspect status again. Do not connect a remote.
git init
git statusYou should see an initialized repository and an untracked Markdown file. Nothing has been uploaded.
Completion checklist
- I check the current directory before important commands.
- I can distinguish source, configuration, dependency, and generated files.
- I understand why a development server keeps running.
- I know that client-prefixed environment variables are public.
- I will rotate an exposed secret instead of merely deleting it.