# Your first command: know what will run

A colleague asks you to inspect one ticket from North workshop. You will use
a small command-line program, then deliberately run it in the wrong folder.
The point is to understand what the command actually did before accepting
an agent's explanation or a green process result.

This original 35-minute exercise uses Node.js 24 and fictional files.
There is no model, provider account, package installation or customer service.
The interactive version is in the protected Academy lesson; the runnable
exercise and all instructions here are free.

## 1. Separate the window from the program

A **terminal** displays text and delivers your keystrokes. A **shell**
interprets command lines and starts programs. Bash, zsh and PowerShell are
shells, with differences in syntax. A **command-line interface (CLI)** is
the operations and options a program accepts through text arguments.

**Node.js** is a runtime: it executes JavaScript outside the browser.
Our `.mjs` file is the program it runs. A **coding agent** is a separate
application that may use a model to propose commands and inspect results.
An ordinary terminal command does not automatically involve an agent.

```text
You type in the terminal
        |
        v
The shell interprets the command
        |
        v
Node.js runs the JavaScript helper
        |
        +--> stdout: the report
        +--> stderr: the note or diagnostic
        +--> exit code: the process result
```

Think of a function call with an operation and inputs. The analogy has a
limit: a command also has a working directory, an environment and system
permissions. Those details matter when an FDE works across customer systems.

## 2. Prepare the small local workshop

Download [First command · Node.js](/templates/fde-first-command.mjs) into a
new folder. Open your terminal in that folder. Check your runtime and run
the reproducible comparisons:

```shell
node --version
node fde-first-command.mjs test
node fde-first-command.mjs compare
node fde-first-command.mjs init
```

Use Node.js 24. Eight checks exercise actual child processes, folder-dependent
reads, argument handling, diagnostics, bounded input and preservation of an
existing workshop. `compare` prints five cases from temporary synthetic files
and removes only its own temporary directory.

`init` creates this new folder beside your download:

```text
fde-first-command.mjs
cli-workshop/
  north/
    project brief.json   → North workshop, tickets N-1 and N-2
  south/
    project brief.json   → South workshop, tickets S-1 and S-2
```

If `cli-workshop` already exists, `init` refuses to overwrite it. Keep your
work and use a different parent folder if you need a fresh workshop.
`inspect` reads its chosen file; it does not edit it. Installing Node itself
may need internet access; the exercise uses the installed standard library
and makes no network requests.

## 3. Read the command before pressing Enter

In Bash, zsh or PowerShell:

```shell
cd cli-workshop/north
node ../../fde-first-command.mjs inspect --file "project brief.json" --limit 1
```

In Windows Command Prompt:

```shell
cd cli-workshop\north
node ..\..\fde-first-command.mjs inspect --file "project brief.json" --limit 1
```

| Piece | What it does here |
| --- | --- |
| `node` | Runs the JavaScript runtime |
| `../../fde-first-command.mjs` | Names the script two folders above the current location |
| `inspect` | Selects the helper's operation |
| `--file` | Names an option |
| `"project brief.json"` | Groups a filename with a space into one argument |
| `--limit 1` | Supplies an option and its value |

The grouping quotes are not part of the filename. The helper receives the
filename as one string. Its `--limit` value also arrives as text; the helper
checks that it is from 1 to 3 before converting it to a number.

The comparison runner passes argument arrays to a fixed Node executable
with `shell: false`. It records actual process outputs, but it does not
exercise a shell parser, PATH lookup or a coding agent. The displayed
commands are the equivalent commands for a learner to type.

In an ordinary shell, PATH helps locate executable names such as `node`.
Built-in commands such as `cd` may be handled by the shell itself. Use the
installed shell's help for its exact rules. Do not treat every tool's flags
as interchangeable.

## 4. Follow the working directory

The **current working directory** is the folder from which relative file
paths start. It is not necessarily the folder containing the script.

After the North command, move to the neighboring folder and repeat it.
In Bash, zsh or PowerShell:

```shell
cd ../south
node ../../fde-first-command.mjs inspect --file "project brief.json" --limit 1
```

In Windows Command Prompt:

```shell
cd ..\south
node ..\..\fde-first-command.mjs inspect --file "project brief.json" --limit 1
```

The arguments are unchanged. The report now names South workshop because
that is where the relative filename was read. Both runs can exit 0.
Only the North result answers the original task.

Change `--limit 1` to `--limit 2` and predict the ticket count. Then change
it to `--limit 0`: the helper should refuse that value. Change one input
at a time so the observation has a clear cause.

## 5. Inspect three separate results

**stdout**, standard output, contains this helper's JSON report.
**stderr**, standard error, contains its note or diagnostic.
The **exit code** is a separate numeric result when the program finishes.

| Case | stdout | stderr | Exit code |
| --- | --- | --- | --- |
| North folder, ordinary arguments | North report | Training-fixture note | 0 |
| South folder, same arguments | South report | Training-fixture note | 0 |
| Missing filename | Empty | Input diagnostic | 2 |
| Misspelled `--limti` | Empty | Usage diagnostic | 2 |
| Limit outside 1–3 | Empty | Usage diagnostic | 2 |

A terminal may show both channels together. Text on stderr does not
necessarily mean failure: the ordinary run writes an explanatory note there.
This program defines 0 as completion and 2 as refused arguments or input.
Other programs define their own nonzero results.

Check status immediately after the command, using the syntax for your shell:

```shell
# Bash or zsh
echo $?
```

```powershell
# PowerShell: after a native executable such as node
$LASTEXITCODE
```

```bat
REM Windows Command Prompt
echo %ERRORLEVEL%
```

A later command can change the saved status. Do not type all three variants;
choose the one for the shell you are using.

Try the refusal from either workshop folder:

```shell
node ../../fde-first-command.mjs inspect --file missing.json --limit 1
```

Use `..\..\fde-first-command.mjs` in Command Prompt. Expect an empty report,
an input diagnostic and exit code 2. The helper limits input to 8 KiB and
does not include supplied file contents or raw exception paths in diagnostics.
Its JSON report is local output from the file you explicitly selected.

## 6. Explain what a successful command does not prove

The South run is a successful process and an unsuccessful answer to the North
task. Keep both facts. A model summarizing the output cannot change which
folder the process used.

Before approving an agent's proposed command, identify the executable,
working directory, arguments and expected effects. Afterwards inspect the
actual report, diagnostic and process result. This exercise only reads
fictional files; it establishes no permission to run a command in a customer
environment and measures no agent behavior.

Keep a short command note:

1. What task was requested?
2. Which program and operation ran, and in which folder?
3. What arguments and effects were expected?
4. What appeared on stdout and stderr, and what was the exit code?
5. Did that observation answer the intended task?

For a transfer exercise, imagine an agent reports that tests passed but the
command ran in a neighboring checkout. Preserve that output, identify the
intended checkout and test command, and obtain evidence from the right place.

Continue with [repository orientation in the Claude Code course](/app/academy?course=claude-code&lesson=setup&view=focus).
It uses the existing offline ticket-triage project and a real failing test.

## Primary references and further learning

Checked 20 October 2026. The workshop, program and instructional examples
above are original LockedIn Labs material.

- [Node.js: arguments, working directory and process output](https://nodejs.org/docs/latest-v24.x/api/process.html)
- [Node.js 24.12: child processes and shell behavior](https://nodejs.org/download/release/v24.12.0/docs/api/child_process.html)
- [Node.js 24.12: parsing command-line options](https://nodejs.org/download/release/v24.12.0/docs/api/util.html#utilparseargsconfig)
- [MIT Missing Semester: Course overview and the shell](https://missing.csail.mit.edu/2020/course-shell/) — the creator's 2020 Unix-oriented lecture and exercises. Use current documentation for runtime installation and shell-specific differences.