Daniel Kim
106eceb864
* up --remote: find orx via ~/.cargo/bin on non-interactive PATH; bump 0.1.59
The remote preflight and launch run orx over a non-interactive ssh shell,
which skips ~/.bashrc/~/.profile — so on a minimal image (RunPod's Ubuntu)
~/.cargo/bin isn't on PATH and 'command -v orx' fails even though 'which orx'
works when logged in. Wrap both remote commands in a PATH prelude that
prepends ~/.cargo/bin and ~/.local/bin (the two common installer targets),
with $HOME left for the remote shell to expand so it works for root or the
runpod user. The 'not installed' error now names those paths and the
install command.
Tests: remote_shell prepends both dirs and keeps $HOME literal; remote_up_cmd
still carries the port behind the prelude.
* up --remote: run remote orx under POSIX sh -c; cover CARGO_HOME
Harden the non-interactive-PATH fix so `orx up --remote` works on any box,
not just RunPod:
- Force POSIX sh. ssh runs the preflight and launch under the remote user's
*login* shell, which may be csh/tcsh/fish — none understand `export VAR=val`,
so the previous `export PATH=...; cmd` was a syntax error there and got
misreported as "unreachable"/"not installed". Wrap the POSIX body in
`sh -c <sh_quote(body)>` so /bin/sh interprets it whatever the login shell is
(mirrors how the job backends run their payload through an explicit shell).
- Cover a relocated CARGO_HOME. The installer honors $CARGO_HOME
(install-path = CARGO_HOME); search ${CARGO_HOME:-$HOME/.cargo}/bin instead
of a hardcoded ~/.cargo/bin so a box that relocates cargo still resolves orx.
- Split the preflight outcome: ORX_MISSING -> clear "not installed"; neither
marker (ssh exited 0 but no answer) -> a distinct message that echoes what we
saw, instead of lumping it into "not installed".
Verified end-to-end that the generated command resolves orx under /bin/sh,
bash, and a tcsh login shell, with orx only in ~/.cargo/bin, with a relocated
CARGO_HOME, and reports ORX_MISSING when genuinely absent.
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 install-skills [--agent claude|codex|opencode|cursor|all] |
Installs the orx skill shim into local coding agents (Claude Code, Codex, OpenCode, Cursor) so they auto-discover the CLI (orx login also offers this). |
orx projects [--all] |
Lists your projects, grouped by organization. --all includes archived. |
orx compute [--gpu <id>] [--count <n>] [--provider <name>] | --cpu] |
Lists the GPU compute catalog across all providers and regions, or CPU-only offers with --cpu, sorted by price. |
orx instance create <orgId> (--gpu <id> [--count <n>] [--disk <gb>] [--provider <name>] | --cpu <flavor> [--vcpus <n>]) |
Spins up a standalone instance in an organization (not tied to an experiment), like the dashboard's "Spin up". |
orx exp status <expId> |
Shows an experiment's status, branch, parent, run command, and latest run, plus a local git diff recipe for what the run changed. |
orx exp cmd <expId> [--set <command>] |
Views or sets the experiment's run command. |
orx exp run <expId> (--gpu <id> [--count <n>] [--disk <gb>] [--provider <name>] | --cpu <flavor> [--vcpus <n>] | --sandbox <id>) |
Launches a run on new GPU, new CPU-only, 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(mode0600).
How login works
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.
Usage analytics
orx sends anonymous usage analytics to help us understand which features
are used and prioritize accordingly. This is opt-out; the orx up dashboard
surfaces the choice as a step in first-run onboarding.
What is collected — the command name that was run, a random per-install UUID,
the CLI version, your OS/architecture, whether the run is in CI, and a small set
of coarse labels for key events (e.g. an experiment was created or a run was
launched, and a broad compute target like modal/k8s/local).
What is never collected — no code, prompt text, file contents, file paths, project/experiment ids or names, repo names, tokens, emails, or any other personal or identifying data. The install UUID is random and not tied to your account.
How to opt out — either:
orx telemetry off # persistent, per-machine
orx telemetry status # see current state + the anonymous install id
orx <cmd> --no-telemetry # per-run
Events are sent fire-and-forget on a background task with a short timeout, so
they never meaningfully block or fail a command (at most a brief flush window on
exit). Every event carries a ci property, so automated runs can be filtered in
analytics without being dropped up front.