Skip to content

Document npm CLI getting started #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fakechris merged 1 commit into from
Apr 18, 2026
Merged

Document npm CLI getting started #20

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 41 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,37 @@ See [docs/current-status.md](docs/current-status.md), [docs/milestones.md](docs/
- `docs/vision.md` — current product vision
- `docs/milestones.md` — active milestones and sequencing

## Install the CLI

The published CLI is the fastest way to use Involute against an existing server:

```bash
npm install -g @turnkeyai/involute
involute --help
```

Or install it project-locally:

```bash
npm install @turnkeyai/involute
npx involute --help
```

Point the CLI at your Involute API:
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Since both global and local installation methods are shown, it's helpful to clarify that the subsequent examples assume a global installation. Users who chose the local path will need to use npx involute instead of just involute.

Suggested change
Point the CLI at your Involute API:
Point the CLI at your Involute API (use `npx involute` if installed locally):


```bash
involute config set server-url https://involute.example.com/graphql
involute config set token YOUR_AUTH_TOKEN
involute teams list
```

Import and verify one team snapshot:
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The involute import team command requires the DATABASE_URL environment variable to be set, as it connects directly to the database via Prisma. This is not required for the API-based commands like teams list. Explicitly mentioning this requirement prevents users from encountering connection errors when following this 'fastest' path.

Suggested change
Import and verify one team snapshot:
Import and verify one team snapshot (requires `DATABASE_URL` to be set):


```bash
export SOURCE_API_TOKEN='src_api_xxx'
involute import team --token "$SOURCE_API_TOKEN" --team SON --keep-export --output ./son-export
```

## Environment

Create a repo-root `.env` file based on `.env.example`:
Expand Down Expand Up @@ -68,7 +99,9 @@ Optional web runtime variables:
- `VITE_INVOLUTE_AUTH_TOKEN` — trusted local/dev bearer token for bypassing browser login
- `VITE_INVOLUTE_VIEWER_ASSERTION` — signed viewer assertion to act as a specific user without exposing the server secret

## Quick start
## Local stack quick start

Use this path when you want to run the API, web app, and Postgres locally.

```bash
pnpm install
Expand Down Expand Up @@ -249,7 +282,13 @@ Set your source-system API token in the shell:
export SOURCE_API_TOKEN='src_api_xxx'
```

Run the end-to-end team import inside the compose CLI container:
If you installed the published CLI:

```bash
involute import team --token "$SOURCE_API_TOKEN" --team SON --keep-export --output ./son-export
```

If you are using the local compose stack, you can also run the import inside the compose CLI container:

```bash
docker compose run --rm cli import team --token "$SOURCE_API_TOKEN" --team SON --keep-export --output /exports/son-export
Expand Down
Loading