Fydell CLI

Requirements

• Node 20 or newer. Check with node --version.
• Windows. Your session is encrypted with Windows DPAPI for your user account. On macOS the CLI uses the login Keychain, which has not been tested yet. Other systems are refused at sign-in (exit code 7).
• A Fydell account. Sign up free if you do not have one.

Quick start

The same steps print with fydell quickstart. Inside a task folder, simulation run and simulation submit find the task themselves. Inside a repository selected with fydell init, inspect, evidence and report find it themselves; elsewhere, name the folder.

# check your setup (never prints tokens)
fydell doctor

# sign in: your browser opens; click Allow
fydell login

# see your invitations and tasks
fydell tasks

# accept, then set up and start (asks before the timer starts)
fydell task accept <invitationId>
fydell simulation init <attemptId>

# work in your editor; run your own tests from the task folder
fydell simulation run -- npm test

# write the handoff, then submit
fydell task show <attemptId> --handoff-template > handoff.md
fydell simulation submit --handoff handoff.md

# Engineering Passport: from inside your repository, select it, look, approve, then upload
fydell init
fydell inspect
fydell evidence review
fydell evidence submit
fydell report

Signing in

fydell login opens Fydell in your browser. Sign in if asked, then click Allow on the “Allow the Fydell command line” page. The terminal waits until you click Allow; it does not finish on its own. If you did not start a sign-in, close the page and nothing is sent. fydell auth login is the older name and does the same thing.

Commands

fydell help <topic> explains one area in the terminal. Topics: quickstart, login, init, inspect, evidence, report, import, connections, simulation, tasks, capture, transcripts, privacy, exit-codes.

Options

Simulations from your terminal

• simulation init accepts the terms, finishes setup and writes the task files to a new folder (by default under Documents\Fydell; a folder that already has other files is refused). It asks before starting the timer, which runs on Fydell's server.
• run executes only the command you pass after --, for example fydell simulation run -- npm test, in the task folder on your computer. Its exit code and the last 64 KB of output, redacted, are recorded on your computer only. Results from Fydell's sandbox come from fydell task test and are labeled as such.
• submit shows what will be sent, asks, then freezes the exact bytes on your computer before sending. A retry after a crash or a dropped connection sends the same bytes with the same submission ID, and Fydell records one submission. The receipt shows the submission ID, scenario and version, server time, SHA-256, files, analysis status and a link.

Repositories on GitHub

The CLI imports only repositories you shared through the read-only Fydell GitHub app, public or private. It never accepts a typed URL or someone else's repository. Share repositories in Fydell under Connections, or run fydell project connect, which lists what is shared and opens the install page.

# See which repositories are shared
fydell project connect

# Revision, files, languages and exclusions. Nothing is imported.
fydell import preview your-name/your-repo

# Asks, then queues that exact commit for analysis
fydell import submit pv-<id>

# Follow the analysis
fydell jobs <job-id>

• Every source file is read. There is no file count limit. Dependencies, build output, lockfiles, binaries and files that look like credentials are skipped, files over 512 KB are left out, and each analysis lists every exclusion with its reason.
• Imports need your confirmed GitHub account. Fydell refuses to analyze a repository shared from GitHub until you have signed in with GitHub on the Connections page. A finding counts as your work only where blame at the analyzed commit shows your verified account wrote the cited lines.
• Reports start private. A new report waits for your approval in Fydell before any share link, profile or application can show it.

Projects on GitLab

Sign in with GitLab under Connections and choose the projects Fydell may read. Fydell asks GitLab only for read_user and read_api, which cannot change anything on GitLab, and stores the sign-in encrypted. Then name a project with its gitlab: prefix.

# Same preview and submit as GitHub
fydell import preview gitlab:your-group/your-project
fydell import submit pv-<id>

• Only projects you chose, and only ones you can still open. Fydell lists projects where your GitLab account is at least a Reporter and re-checks your access before and during every analysis.
• Lines are credited by email. GitLab blame names authors by email address, so Fydell credits a line to you only when its commit uses an address GitLab has confirmed for your account, or your GitLab private commit address. Someone else committing under one of your addresses would also match; each report says so.
• Disconnecting revokes access. Disconnecting GitLab in Fydell revokes the sign-in at GitLab and stops all sharing. Your existing reports are unchanged.

What is collected, and what is not

The CLI reads only the repository you select with fydell init or name on the command line; pass . for the current folder. It never scans your computer, and a home folder or the top of a drive is refused. init, inspect and evidence review never use the network.

• Source files only. Dependency, build and editor folders stay on your computer, as do binaries, generated files and lockfiles.
• Credentials stay behind. Environment and credential files, and any file containing text that looks like a credential, are left out and listed so you can see what was kept back.
• You approve it before it is sent. inspect and evidence review send nothing. evidence review lists every file that would upload, every exclusion with its reason and possible sensitive information, and records that list as the evidence you approved. evidence submit uploads only that evidence, asks first, and refuses if the folder changed since the review. simulation submit also prints what would be sent and asks first. Nothing is analyzed on your computer: analysis happens on Fydell's servers after upload.
• Nothing in your folder runs. Collecting never executes package scripts, builds or git: commit and branch details are read from the files in .git directly. The only command the CLI ever runs is the one you pass to simulation run after --.
• Agent transcripts are separate. Transcripts and chat history from AI coding agents (.cursor, .claude, .specstory, .aider files and similar) are never collected. Sharing editor history is a separate opt-in in your Engineering Passport.
• No surprises from links. Symbolic links and junctions are never followed, and nothing outside the folder is read.
• Limits. Up to 300 files and 5 MB packed for folders you upload; task folders follow the task's own limits. Repositories imported through the GitHub app have no file count limit.

Interrupted uploads

If fydell evidence submit stops partway (network, Ctrl+C, a server error), run it again. While the folder still matches your review it resumes with the same files instead of starting over. Identical files are never stored twice. fydell status shows whether a submit is waiting to be resumed. An interrupted simulation submit works the same way.

Where it keeps things

• Selected repositories, collection and review records, frozen submissions, run logs and the encrypted session live in %LOCALAPPDATA%\Fydell\cli, never inside your project. Set FYDELL_CLI_HOME to use another folder.
• Tokens are never written in plaintext, never put in a config file or log, and never printed. The session is encrypted with Windows DPAPI for your user account and passed to the encryption step over stdin, never on a command line.
• fydell doctor checks the state folder for plaintext tokens and redacts its own output. fydell auth logout deletes the stored credential and revokes the session on the server.

Exit codes

Scripts can rely on these. With --json, failures also print { "ok": false, "error": { "code", "message", "exitCode" } }.

After uploading

Each submit is a new version of the project in your Engineering Passport; earlier versions stay. fydell report shows the Builder Report's status and opens it, and you choose which projects and versions anyone sees when you share or apply. Read Trust and security for who can read what.