mirror of https://github.com/alphaXiv/OpenResearch.git synced 2026-11-12 10:05:24 +08:00

Files

T

Daniel Kim e888995821 Add orx version / orx update and a passive update nudge

- `orx --version` (clap) and `orx version [--check] [--json]`: prints the
  CLI version and compares it to the latest GitHub release. `--json` is
  the agent-facing form (stable stdout object, exit 0 either way).
- `orx update [--dry-run] [--force]`: updates in place by re-running the
  cargo-dist release installer pinned to the existing install prefix
  (CARGO_DIST_FORCE_INSTALL_DIR), the same mechanism as axoupdater/uv but
  without the native-tls dependency that conflicts with our musl builds.
  Guarded by the cargo-dist install receipt (refuses cargo-install copies,
  path/version mismatches, Nix/Homebrew paths, unwritable bin dirs), an
  exclusive flock against concurrent updates, and run via `sh script` so
  noexec /tmp mounts don't break it.
- Passive nudge: at most one background latest-version check per 24h
  (cached in the config dir), printed to stderr only on interactive
  terminals, never in CI/pipes, never altering exit codes. Opt out with
  ORX_NO_UPDATE_CHECK, NO_UPDATE_NOTIFIER, or OPENRESEARCH_CLI_DISABLE_UPDATE=1.

Latest-version discovery uses the releases/latest/download/dist-manifest.json
permalink (CDN redirect, no GitHub API rate limit) instead of the REST API,
whose 60 req/h/IP unauthenticated cap is routinely exhausted on the
datacenter IPs agents run from.

2026-06-11 14:17:15 -07:00

3.1 KiB

Raw Blame History

OpenResearch CLI (`orx`)

A small command-line interface for OpenResearch. Log in via the browser, then query your projects from the terminal.

Requirements

Rust (stable) with Cargo. Install via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build & run

# Build (debug):
cargo build

# Run during development:
cargo run -- login
cargo run -- projects

# Build an optimized release binary at target/release/orx:
cargo build --release
./target/release/orx login

# Or install `orx` onto your PATH (~/.cargo/bin):
cargo install --path .
orx login
orx projects

Run the tests with cargo test.

Commands

Command	Description
`orx login [--api-url <url>]`	Opens your browser, authenticates, and stores a personal access token.
`orx logout`	Removes the stored token.
`orx projects [--all]`	Lists your projects, grouped by organization. `--all` includes archived.
`orx compute [--gpu <id>] [--count <n>]`	Lists the GPU compute catalog, sorted by price.
`orx exp status <expId>`	Shows an experiment's status, run command, and latest run.
`orx exp cmd <expId> [--set <command>]`	Views or sets the experiment's run command.
`orx exp run <expId> (--gpu <id> [--count <n>] [--disk <gb>] \| --sandbox <id>)`	Launches a run on new or existing compute.
`orx exp cancel <expId>`	Cancels the in-flight run.
`orx lit "<query>" [--limit <n>] [--json]`	Full-text search alphaXiv's paper corpus (no login required).
`orx paper <id\|url> [--full]`	Fetch a paper's machine-readable report, or its full text with `--full`.
`orx version [--check] [--json]`	Prints the CLI version; `--check` compares it to the latest release.
`orx update [--dry-run] [--force]`	Updates orx by re-running the release installer (installer installs only).

Updating

orx update only manages binaries installed by the release installer script (it checks the cargo-dist install receipt at ${XDG_CONFIG_HOME:-~/.config}/openresearch-cli/). If you installed with cargo install, update the same way instead. In interactive terminals orx also checks for new releases in the background at most once a day and prints a one-line notice to stderr; set ORX_NO_UPDATE_CHECK=1 (or OPENRESEARCH_CLI_DISABLE_UPDATE=1) to turn that off. Agents, scripts, pipes, and CI never see the notice.

Configuration

API URL resolves from --api-url → OPENRESEARCH_API_URL → the built-in default (http://localhost:4000). Point it at the production API host for real use:
```
export OPENRESEARCH_API_URL=https://api.openresearch.sh
```
Credentials are stored at ${XDG_CONFIG_HOME:-~/.config}/openresearch/credentials.json (mode 0600).

orx login starts a temporary HTTP listener on a random 127.0.0.1 port, opens {api}/auth/cli/login in your browser, and waits for the API to redirect back with a freshly minted personal access token after you authenticate. The token is sent as Authorization: Bearer … on every subsequent request.

3.1 KiB Raw Blame History

OpenResearch CLI (orx)