Quickstart

Install the Factrove CLI, or run the repository locally, create an API key, and upload an HTML file.

​

Install the CLI

The published npm package is factrove. It installs factrove and ftrv. Both run the same program. Node.js must be at least 24.7 and below 25.

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

npx factrove --help runs it without a global install.

With no profile and no API URL, the CLI calls https://api.factrove.app. factrove configure, --api-url, --endpoint-url, and FACTROVE_API_URL override that origin. A self-hosted API needs the override. Release the CLI is how a maintainer publishes a version. Nothing publishes on push.

The rest of this page runs the local repository. From the repository root, contributors use pnpm factrove instead of the global install. pnpm prints the script line it runs to stderr.

​

Get the source

Clone magnificode-ltd/factrove and change into that directory:

git clone https://github.com/magnificode-ltd/factrove.git
cd factrove

You need Node.js 24.x, at least 24.7 and below 25 (>=24.7.0 <25 in package.json engines; 24.16 is pinned), pnpm 11.25, and Docker Compose v2.

• Node.js downloads
• pnpm installation
• Docker Compose

Self-hosting is the Docker Compose install. Troubleshooting covers the failures this loop hits most often.

Install dependencies, then build the CLI and the workspace packages it imports. pnpm factrove refuses to start until apps/cli/dist/main.js exists:

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

pnpm dev builds the CLI again before it starts the servers. A checkout you only use for the CLI still needs the filter build above.

​

1. Configure and start local services

Set BETTER_AUTH_SECRET in apps/api/.env to at least 32 characters before starting the API. The example value is a local placeholder.

cp apps/api/.env.example apps/api/.env
cp apps/cli/.env.example apps/cli/.env
pnpm infra:up
pnpm db:migrate
pnpm db:seed
pnpm dev

pnpm infra:up starts PostgreSQL on 127.0.0.1:5432 and Garage (local S3) on 127.0.0.1:3900. pnpm dev starts the API on http://127.0.0.1:3001 and the web app on http://127.0.0.1:3000. Compose does not start either application. pnpm dev is the local development server.

​

2. Create an account and an API key

Open http://localhost:3000/signup, then create a key at /account/api-keys. The secret is shown once. Creating the account sends an invite email. With EMAIL_TRANSPORT unset or log, the API logs that message and does not send it. A plus-address is a valid invitee. The commands for the log, SMTP, and Brevo transports, with the address as a parameter, are in Invite email. A copyable sign-in and key-creation request is in API overview.

In a second terminal, from the repository root:

pnpm factrove configure

The CLI stores the key in ~/.factrove/credentials (mode 0600). It does not print the key.

​

3. Upload a file

artifact_id=$(pnpm factrove upload ./fixtures/hello.html)
printf '%s\n' "$artifact_id"
pnpm factrove upload ./fixtures/hello.html --name "X launch calendar"

Plain success prints only the artifact id on stdout. pnpm writes the script line it runs to stderr, so the substitution above is the id. Omit --name and the library name is the file name without .html or .htm. A stem that is empty, longer than 120 characters, or not one line stores null, and the upload still succeeds. A later replace keeps that name unless you pass --name again. Open it at:

http://localhost:3000/artifacts/{id}

--json prints the { artifact } envelope on one line. Replace that artifact later with the same file:

pnpm factrove upload ./fixtures/hello.html --artifactId "$artifact_id"

If a replace returns 500, GET the artifact before retrying. Prepare the HTML so it can render under the viewer policy. See Prepare an artifact.

​

4. Open the library

Visit http://localhost:3000. Use My artifacts or Organization artifacts, then Refresh after an upload. An empty My artifacts page shows npm i -g factrove (or npx factrove), ftrv as the same command, factrove configure --api-url for this app’s API origin, and factrove upload, plus a prompt you can paste into a coding agent. The commands in this guide still use pnpm factrove because they run from the checkout. The CLI reference lists every command. Organization artifacts stay empty until the account has a membership. Signup and seed do not create one. See Organization membership.

The owner of a private artifact can choose Share with the organization name in the viewer. After confirmation, members of that organization can open it. The web app cannot make it private again. The owner can also Rename or Delete an artifact from the library and the viewer. Delete asks for confirmation, then removes the artifact, its stored HTML, and any public link.

​

5. Share a link (optional)

pnpm factrove share "$artifact_id" --json

--json prints one { share } line. Plain share output also prints a status line after the URL. Add a password with --password (a prompt that needs a terminal) or --password-stdin. See Sharing links.

​

Useful follow-ups

pnpm factrove list
pnpm factrove get "$artifact_id" --format markdown > artifact.md
pnpm factrove rename "$artifact_id" --name "X launch calendar"
pnpm factrove upload ./fixtures/hello.html --artifactId "$artifact_id"
pnpm factrove share "$artifact_id" --revoke
pnpm factrove delete "$artifact_id" --yes

A copyable agent workflow is in CLI. Help text still uses synopsis placeholders such as <artifact-id>. Those are not shell syntax. Executable examples on this site use quoted variables.

pnpm factrove reads apps/cli/.env only for unset FACTROVE_API_URL and FACTROVE_PROFILE. The example sets FACTROVE_API_URL to http://localhost:3001 so that command talks to the local API. node apps/cli/dist/main.js and the published factrove command do not read that file. Their built-in origin is https://api.factrove.app. See CLI for flags and precedence.