Turing Guild Labs

Back to course

Lab

Lab: Discovering an Unknown CLI

Submit this lab

Lab: Discovering an Unknown CLI

Objective

Install and investigate an unfamiliar command-line tool called fubar, then compare your manual discovery process with how Codex investigates and operates the same CLI.

You will not be told what fubar does ahead of time. Your job is to discover its purpose and capabilities by using the same process a careful developer or AI coding agent uses when encountering an unfamiliar tool:

  1. Ask the tool what it can do.
  2. Read help output carefully.
  3. Form a hypothesis.
  4. Run a safe experiment.
  5. Observe the result.
  6. Verify what changed.

This lab is not about memorizing commands. It is about learning how to investigate an unfamiliar technical tool.

Success Criteria

You have successfully completed this lab when you can:

  • Create a dedicated lab project folder inside your labs parent folder.
  • Clone and install the fubar CLI project.
  • Confirm that fubar runs with fubar --version and fubar --help.
  • Use help output to build a command map before making changes.
  • Run command-specific help for at least three commands.
  • Identify commands that appear read-only before using commands that change state.
  • Run at least two read-only investigation commands.
  • Make one careful state-changing command and verify the result.
  • Test whether fubar supports structured output such as JSON or JSONL.
  • Record your notes in discovery-notes.md.
  • Compare your manual CLI discovery process with Codex's CLI discovery process.
  • Ask Codex to operate fubar using natural language and verify the result.
  • Submit a screen-recorded video demonstration.
  • Turn your lab directory into a public GitHub repository and submit its URL.

Instructions

  1. Open your terminal.

For this lab, your terminal is where you type the commands yourself.

  • On macOS, use Warp.
  • On Windows, open PowerShell first, then enter WSL by running:
wsl

After you are inside WSL, run the lab's terminal commands there.

Do not use Warp AI, Codex, ChatGPT, or another AI assistant to tell you what fubar does during your first manual investigation.

The goal is for you to personally practice the discovery process first. After that, you will use Codex to compare your process with how an AI coding agent approaches the same CLI.

  1. Go to your labs parent folder. If it does not exist yet, create it:
cd ~
mkdir -p labs
cd labs
pwd
  1. Create a folder for this lab and move into it:
mkdir cli-discovery
cd cli-discovery
pwd

For the rest of this lab, your notes and submitted files should live inside this cli-discovery folder.

  1. Open the lab folder in VS Code:
code .

VS Code is the editor we will use when editing files in this course. Leave Warp open for terminal commands, and use VS Code for notes and any file edits.

  1. Create a file named discovery-notes.md in VS Code.

Use this file to record your hypotheses, command map, observations, checkpoint answers, and final reflection.

  1. Clone the fubar repository inside your lab folder:
git clone https://github.com/iitgrad/fubar-cli.git

Then move into the cloned project folder:

cd fubar-cli
pwd
  1. Install the project dependencies:
bun install
  1. If the project includes a build step, run it:
bun run build

If there is no build script, write that down in discovery-notes.md and continue.

  1. Link the CLI so you can run it as a command:
bun link
  1. Confirm that fubar is available:
fubar --version
fubar --help

In discovery-notes.md, answer:

Installation Check
Did the installation work?
What command confirmed that fubar was available?
What did fubar --help show you at first glance?
  1. Start your manual discovery with the top-level help command:
fubar --help

Read the output carefully. Do not rush into running state-changing commands yet.

Look for clues:

  • What commands are available?
  • What nouns or objects does fubar seem to care about?
  • Which commands look like they only display information?
  • Which commands might create, update, or delete something?
  • Are there global options or flags?
  • Does the CLI mention JSON, JSONL, verbose output, debug output, or configuration?

In discovery-notes.md, write your first theory:

Based on the help output, I think fubar is probably used for...

It is okay if your first theory is wrong. Discovery means updating your model as you gather evidence.

  1. Build a command map.

Use command-specific help to investigate at least three commands:

fubar COMMAND_NAME --help

For example, if fubar had a command called status, you would run:

fubar status --help

In discovery-notes.md, record:

Command Map
Which command seems safest to run first?
Which command seems most important?
Which command seems like it might change data?
What evidence helped you decide?
  1. Read before write.

Before using any command that changes something, look for commands that inspect current state.

These might have names like:

  • list
  • show
  • status
  • get
  • describe
  • info

Your actual commands may be different. Use fubar's help output to decide.

Run at least two read-only commands.

After each command, record in discovery-notes.md:

What did the command show?
Did it confirm or change your theory about fubar?
What would you try next?
  1. Make one careful change.

Choose one command that appears to create, update, or modify something.

Before you run it, say your prediction out loud and write it in discovery-notes.md:

I think this command will...

Then run the command.

After running it, verify the result using another command. For example, if you created something, use a list or show command afterward to confirm it exists.

Change only one thing at a time. If you run five commands at once, it becomes hard to know which command caused which result.

  1. Look for structured output.

Many professional CLIs support output designed for software, not just humans. Look for options such as:

--json

or:

--jsonl

If fubar supports structured output, run one command twice.

First, run the normal version:

fubar SOME_COMMAND

Then run the structured version:

fubar SOME_COMMAND --json

or:

fubar SOME_COMMAND --jsonl

In discovery-notes.md, answer:

Which output is easier for a human to read?
Which output would be easier for software to parse?
Why might an AI coding agent prefer JSON output?

If fubar does not support structured output for the command you chose, explain how you discovered that.

  1. Write your final manual explanation in discovery-notes.md.

Answer:

What is fubar for?
What are its most important commands?
What data or objects does it manage?
How did you figure that out?
What command would you tell a classmate to run first?
What command should a classmate be careful with?
  1. Reset fubar before Codex investigates it:
fubar clear

If fubar asks you to confirm, read the prompt carefully and follow the CLI's instructions.

In discovery-notes.md, answer:

What did fubar clear appear to do?
Did the command ask for confirmation?
Why might it be useful for Codex to start from an empty or reset state?
  1. Open Codex and create a new project. Pick a folder name in your labs directory and call it cli-discovery.

Ask Codex this prompt:

what can you tell me about the command fubar.

Codex should not inspect the source code for this part (which is actually in a different directory anway). The goal is to watch it discover the command by using the CLI itself.

As Codex works, pay attention to:

  • What command it runs first.
  • Whether it uses --help.
  • Whether it checks the version.
  • Whether it investigates subcommands.
  • Whether it starts with read-only commands.
  • Whether it explains its reasoning as it goes.
  • Whether its discovery process looks similar to yours.

In discovery-notes.md, answer:

What did Codex try first?
Did Codex use a similar process to yours?
Did Codex discover anything you missed?
Did Codex make any assumptions?
Did Codex avoid looking at the repository source code?
What did you learn by watching Codex use the CLI?
  1. Ask Codex planning questions.

Try prompts like these:

what are the different objects that we can create with fubar?

how would we create three rooms in a house?

At this stage, you are not asking Codex to make changes yet. You are asking it to explain what it thinks is possible and what commands it would use.

In discovery-notes.md, answer:

What did Codex identify as creatable objects?
What commands did Codex say it would use?
Did Codex explain its reasoning from help text or command output?
Did its explanation match what you discovered manually?
  1. Let Codex operate fubar.

Give Codex a natural-language request like this:

Using only the fubar command, create a kitchen, bathroom, and bedroom in a home called `My Home`. Tell me which commands you are running as you do it.

You may use a different home name if you want, but keep the request specific.

Watch what Codex does. Pay attention to how natural language gets turned into command-line actions.

In discovery-notes.md, answer:

What commands did Codex run?
Did Codex ask for clarification, or did it proceed?
Did Codex create the home and rooms successfully?
How could you tell?
  1. Ask Codex to inspect the result.

Try prompts like:

what rooms do we have in the house?

how many rooms do we have?

Codex should answer by running fubar commands, not by guessing.

In discovery-notes.md, answer:

What command did Codex use to inspect the state?
Did the result match what Codex created earlier?
Why is verification important when an AI agent changes something?
  1. Write your final reflection in discovery-notes.md.

Answer:

How was your manual discovery process similar to Codex's discovery process?
How did Codex move from discovering the tool to using it through natural language?

Mention at least two of these ideas:

  • Reading help output.
  • Inspecting subcommands.
  • Starting with read-only commands.
  • Forming hypotheses.
  • Running small experiments.
  • Verifying results.
  • Using structured output like JSON.
  • Avoiding destructive commands until the tool is understood.
  • Explaining reasoning while working.
  • Translating natural-language requests into CLI commands.
  • Verifying state after making changes.
  1. Prepare your lab folder for GitHub submission.

Move back to the parent cli-discovery folder:

cd ..
pwd

Your path should end with:

labs/cli-discovery

Because fubar-cli was cloned from an existing Git repository, remove its nested Git metadata before creating your own lab repository:

rm -rf fubar-cli/.git

This does not delete your fubar-cli files. It only removes the cloned repository's hidden Git history so your cli-discovery folder can become one clean submission repository.

Verify your required files and folder are present:

ls

You should see:

discovery-notes.md
fubar-cli

Required Deliverables

Submit both:

  • A short screen-recorded video of yourself completing the lab.
  • A public GitHub repository URL for your cli-discovery lab folder.

Your video should include:

  • fubar installed and running.
  • fubar --version.
  • fubar --help.
  • At least three uses of command-specific help.
  • At least two read-only investigation commands.
  • One careful state-changing command.
  • One verification step after making a change.
  • Your manual explanation of what fubar does.
  • fubar clear before handing the CLI to Codex.
  • Codex investigating fubar using the provided prompt.
  • Codex answering planning questions using only the CLI.
  • Codex creating a home and rooms from a natural-language request.
  • Codex inspecting the result with fubar commands.
  • Your comparison of your discovery process with Codex's discovery process.

Your GitHub repository should include:

  • discovery-notes.md
  • the fubar-cli folder
  • any local files created during your investigation or optional stretch work

Submit Your Lab With GitHub

Before you submit, make sure you are inside your lab directory:

pwd

The path should end with:

labs/cli-discovery

Initialize Git, commit your work, create a public GitHub repository, and push it:

git init
git add .
git commit -m "Complete CLI discovery lab"
gh repo create cli-discovery --public --source=. --remote=origin --push

Get the URL for your GitHub repository:

gh repo view --web

Copy the GitHub repository URL from your browser and submit that URL with your lab submission.

Stretch

Teach fubar a New Trick

This stretch objective is optional. Completing it successfully can earn Qubits.

In the main lab, you treated fubar as a black-box CLI. You asked questions by running the command, reading help output, and watching Codex use the CLI without looking at the source code.

For this stretch, you may now let Codex inspect the Git repository.

Your goal is to use Codex as a development partner: have it inspect the fubar codebase, identify one small missing capability, implement that capability locally, and help you test it.

You do not need to push changes back to the original fubar-cli repository. Your public cli-discovery lab repository is enough.

Stretch Step 1: Ask About CRUD

Start by asking Codex:

What does CRUD mean in software development?

Then ask Codex:

Look at this repo and tell me whether fubar supports CRUD for each major object. Make a table of what exists and what seems to be missing.

CRUD usually means:

  • Create
  • Read
  • Update
  • Delete

You do not need to already know this term. Part of the stretch is learning what it means and watching Codex apply it to a real codebase.

Stretch Step 2: Choose One Small Capability

After Codex explains what fubar currently supports, choose one small missing or incomplete capability.

Examples might include:

  • Add a command that updates or renames an existing room.
  • Add a command that deletes a room.
  • Add a command that renames a home.
  • Add a command that lists only rooms in one home.
  • Add JSON output to a command that does not support it yet.
  • Improve help text for a command that is confusing.

Pick something small enough that Codex can implement and test during your stretch attempt.

Stretch Step 3: Ask Codex to Implement It Locally

Once you choose a capability, ask Codex to make the change.

For example:

Add a command to fubar that lets me rename an existing room. Tell me which files you edit, and show me how to test it.

Or:

Add a delete command for rooms. Explain what code you changed, and run a test or demo command to prove it works.

You should use natural language to work with Codex. You do not need to know exactly how to write the code yourself, but you do need to guide the work, ask good questions, and verify the result.

Ask Codex questions like:

  • What file or files do you plan to edit?
  • What behavior are you adding?
  • Is this command safe to run?
  • How can we test it?
  • What command proves the new feature works?

Stretch Step 4: Test the New Capability

After Codex changes the code, test the new capability from the terminal.

Your test should show:

  • The new or changed command exists.
  • The help output explains the command.
  • The command works on a small example.
  • Another command can verify the result.

For example, if you add a room rename command, you might:

  1. Create a test room.
  2. Rename the test room.
  3. List or show rooms to confirm the new name appears.

Stretch Deliverable

If you complete the stretch, add a section to discovery-notes.md that explains:

  • What CRUD means.
  • What missing capability you chose.
  • What files Codex changed.
  • How you tested the new or changed command.
  • What command proved the behavior works.

Your stretch video segment should show:

  • Codex explaining what CRUD means.
  • Codex inspecting the fubar repo.
  • Codex identifying one missing or incomplete capability.
  • You choosing one small feature to add.
  • Codex implementing the change locally.
  • Codex explaining which files it changed.
  • You testing the new or changed command.
  • You verifying that the behavior works.
  • A short explanation of what changed and why it matters.