CLI overview

Install and configure the Factrove CLI, then read the exact help pages generated from the command spec.

The CLI is a standalone NestJS process that calls the HTTP API. It has no listener of its own. The published npm package is factrove. Node.js must be at least 24.7.0 and below 25.

npm install --global factrove
factrove --help
ftrv --help

ftrv is the same program. npx factrove runs it without a global install. With no profile and no API URL, it calls https://api.factrove.app. --api-url, FACTROVE_API_URL, and factrove configure override that origin. Release the CLI is the manual publish. It does not run on push.

From a checkout, contributors use pnpm factrove. Install dependencies and build the CLI plus the workspace packages it imports. The launcher refuses to start until apps/cli/dist/main.js exists:

pnpm install --frozen-lockfile
pnpm --filter @factrove/cli... build
pnpm factrove --help

pnpm factrove reads apps/cli/.env for unset FACTROVE_API_URL and FACTROVE_PROFILE. The example points that command at http://localhost:3001. node apps/cli/dist/main.js and the published commands do not read that file. Set BETTER_AUTH_SECRET and start the API before configure against a local server. See Quickstart and Troubleshooting.

The program help uses the name factrove. The pages that follow reprint factrove --help and each factrove <command> --help text word for word, then list flags that help text omits.

​

Configure once

Create a key in the web app at /account/api-keys, or with the session recipe. Then:

factrove configure --api-url http://localhost:3001

From the repository root, the same step is pnpm factrove configure. ftrv configure is the same command as factrove configure.

See configure. The key is not printed.

​

Commands

Command	What it does
factrove —help	Top-level help
upload	Create an artifact, or replace one with --artifactId
list	List your artifacts, or organization-shared ones with --view org
get	Print stored HTML or converted Markdown
share	Create, password-protect, or revoke a public link
rename	Change the library name
delete	Delete an artifact after confirmation, or with --yes
configure	Save a profile key and API origin

cp is not a Factrove command. Precedence, --endpoint-url, --output json, and the differences from aws s3 are in CLI.

​

Output and errors

• Success exit code is 0. Any failure is 1.
• Plain upload prints only the artifact id. A replace prints the same id. Plain get prints content bytes. Plain share prints the public URL and whether it is password protected. Plain list prints one artifact per line. Plain rename prints Renamed {id}. Plain delete prints Deleted {id}.
• --json and --output json print one JSON line on success. Errors then use {"error":{"code":"...","message":"..."}} on stderr.
• --quiet is accepted on upload, get, share, list, rename, and delete. Help does not list it.
• --profile is accepted on every command. Help lists it on configure.
• Local codes are FILE_NOT_FOUND, INVALID_INPUT, and NETWORK_ERROR. API codes pass through.

A replace can rarely return 500 after the new object is already committed. GET the artifact before retrying.