# orx CLI Subcommands: Complete Guide to OpenResearch Command-Line Tools

> Explore the orx CLI's essential user-facing subcommands like login, exp, compute, and discover. This guide covers authentication, experiment management, and GPU instance control for OpenResearch.

- Repository: [alphaXiv/OpenResearch](https://github.com/alphaXiv/OpenResearch)
- Tags: how-to-guide
- Published: 2026-09-13

---

**The `orx` command-line interface exposes over 20 user-facing subcommands—including `login`, `exp`, `compute`, `discover`, and `up`—for managing authentication, experiments, GPU instances, and literature retrieval, with all commands defined in the `Command` enum in [`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs) and implemented in the `src/commands/` directory.**

The alphaXiv OpenResearch repository provides the `orx` CLI as a Rust-based tool for orchestrating research workflows. Whether you are provisioning GPU compute, tracking experiment runs, or integrating with AI coding agents, mastering the `orx` CLI subcommands allows you to interact with the platform efficiently from your terminal.

## Authentication and Identity

Managing access to the OpenResearch platform starts with authentication commands that handle OAuth tokens and credentials.

### `orx login` and `orx logout`

The `login` subcommand initiates a Loopback OAuth flow that opens your default browser for authentication and stores the resulting personal access token locally. According to the source code, this command is defined in the `Command` enum in [[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L63-L66), with the browser interaction handled by the utility module in [`src/browser.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/browser.rs). The `logout` command ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L66-L68)) removes the stored token from your local configuration.

```bash

# Authenticate and store credentials

orx login

# Remove stored authentication

orx logout

```

## Project and Organization Management

Organize your research work using commands that interface with local project storage and organizational billing contexts.

### `orx projects` and `orx orgs`

The `projects` subcommand lists locally stored projects with optional JSON output formatting, implemented in [[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L69-L71). Similarly, `orgs` lists organizations available for billing compute resources ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L72-L74)).

### `orx project`

For operations on specific projects, the `project` subcommand accepts nested actions such as `view` and `edit` to inspect or modify project metadata ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L75-L78)).

```bash

# List all local projects

orx projects

# View a specific project

orx project view <project-id>

# List billable organizations

orx orgs

```

## Experiment and Run Lifecycle

The core workflow commands enable creating, monitoring, and managing experimental runs on remote compute.

### `orx exp`

The `exp` subcommand provides comprehensive experiment manipulation capabilities including `status`, `desc`, `run`, `cancel`, `wake`, and `wait` actions. This is defined in [[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L99-L104) and implemented in the corresponding command module.

### `orx runs`, `orx logs`, and `orx create-experiment`

- **`runs`**: Lists runs for a project with optional filtering by experiment ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L81-L83))
- **`logs`**: Streams terminal output from a specific run, supporting both tail and full log retrieval ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L84-L86))
- **`create-experiment`**: Adds a new experiment node to your local project structure ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L87-L90))

```bash

# Create a new experiment node

orx create-experiment <project-id> --title "Baseline Model"

# Check experiment status

orx exp status <exp-id>

# Launch a run on H100 GPUs

orx exp run <exp-id> --backend openresearch --flavor h100_sxm

# Stream logs from a running job

orx logs <run-id> --tail

```

## Compute and Instance Management

Provision and manage standalone GPU resources independent of experiment workflows.

### `orx compute`

Displays the available GPU compute catalog with filtering options for GPU type, provider, and device count ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L91-L94)).

### `orx instance`

Manages standalone compute instances with sub-actions `create`, `list`, and `delete` for provisioning resources within specific organizations ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L95-L98)).

```bash

# Browse available GPU configurations

orx compute

# Provision an H100 instance

orx instance create <org-id> --gpu H100_SXM

# List active instances

orx instance list <org-id>

```

## SSH Key Management

Configure secure access to provisioned instances using the `ssh-key` command ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L97-L100)), which supports `add` for registering new public keys and `list` for viewing existing credentials.

```bash

# Register a new SSH public key

orx ssh-key add ~/.ssh/id_ed25519.pub

# List registered keys

orx ssh-key list

```

## Agent Integration and Skills

Integrate the `orx` CLI with AI coding agents through skill management commands.

### `orx agent`, `orx skill`, and `orx install-skills`

- **`agent`**: Spawns a helper coding-agent session for executing brief tasks ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L78-L80))
- **`skill`**: Retrieves usage information for agents or fetches specific skill documents ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L104-L106))
- **`install-skills`**: Installs the `orx` skill shim into supported coding agents including Claude, Codex, Opencode, and Cursor ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L13-L16))

```bash

# Install orx skills for Claude

orx install-skills --agent claude

# Spawn an agent session

orx agent

```

## Library Management

Manage reusable templates and skills in your local library using the `skills` and `templates` subcommands ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L107-L112)), which allow you to add reusable components to your research workflow.

## Literature Retrieval

Access academic papers and search across scientific literature directly from the command line.

### `orx discover`

Executes retrieval primitives including `keyword`, `embedding`, `openalex`, and `biorxiv` search methods ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L117-L121)).

### `orx paper`

Fetches papers by various identifiers including arXiv/alphaXiv IDs, DOIs, or OpenAlex IDs, with optional full-text retrieval ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L124-L128)).

```bash

# Search for papers by keyword

orx discover keyword "deep learning" --limit 5

# Fetch a specific arXiv paper

orx paper 2101.00001v1

```

## Tooling and Maintenance

Administrative commands for version management, local server operation, and system maintenance.

### Version and Update Management

- **`version`**: Displays the current CLI version with an optional `--check` flag to query the latest release ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L124-L127))
- **`update`**: Updates the binary to the latest release with dry-run support ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L127-L131))
- **`install-cli`**: Links the macOS application's `orx` binary onto the user's `$PATH` ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L130-L133))

### Local Development Server

The `serve` subcommand starts a local HTTP/SSE daemon on port 4791 (by default), exposing the run store for use by the web UI and coding agents ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L136-L138)).

### System Operations

- **`up`**: Launches the local autoresearch dashboard, serving as the default UI when running `orx up` ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L144-L148))
- **`supervise`**: Tails backend logs and persists status for local runs ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L139-L142))
- **`delete`**: Removes the local database, CLI executable, or both for cleanup ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L73-L77))
- **`telemetry`**: Controls anonymous usage analytics with options to show, enable, or disable tracking ([[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs)](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs#L148-L151))

```bash

# Check version and available updates

orx version --check

# Update to latest release

orx update

# Launch the local dashboard

orx up

# Start the local API server

orx serve

```

## Summary

The `orx` CLI provides comprehensive functionality for managing the entire OpenResearch workflow:

- **Authentication**: `login` and `logout` commands secure your session with OAuth tokens stored in [`src/config.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/config.rs)
- **Project Management**: `projects`, `orgs`, and `project` commands organize your research workspace
- **Experiment Control**: `exp`, `runs`, `logs`, and `create-experiment` handle the full lifecycle of experimental runs
- **Compute Resources**: `compute` and `instance` manage GPU catalogs and standalone instances
- **Literature Access**: `discover` and `paper` enable command-line search and retrieval of academic papers
- **Integration**: `agent`, `skill`, and `install-skills` connect with AI coding assistants
- **Maintenance**: `version`, `update`, `serve`, and `up` keep the tooling current and accessible

All commands route through the `Command` enum defined in [`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs) (lines 57-110) with implementations residing in the `src/commands/` directory.

## Frequently Asked Questions

### What is the default command when running `orx` without arguments?

Running `orx` without subcommands defaults to the `up` command, which launches the local autoresearch dashboard on `http://127.0.0.1:4791`. This behavior ensures immediate access to the GUI when users simply type `orx` in their terminal.

### How does the `orx` CLI handle authentication tokens?

The CLI stores personal access tokens obtained through the `login` command using the configuration module in [`src/config.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/config.rs). The `login` subcommand utilizes [`src/browser.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/browser.rs) to open the system default browser for Loopback OAuth, while `logout` securely removes these credentials from local storage.

### Can I use `orx` to provision compute without creating an experiment?

Yes, the `instance` subcommand allows direct provisioning of standalone compute resources using `orx instance create <org-id> --gpu <type>`, independent of the experiment workflow managed by the `exp` command. This is useful for ad-hoc development or debugging sessions requiring GPU access.

### Where are the command implementations located in the source code?

Each subcommand is defined in the `Command` enum within [`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/main.rs) (lines 57-110) and implemented in individual modules under `src/commands/`. For example, authentication logic resides in [`src/commands/login.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/login.rs), while compute management is handled in [`src/commands/instance.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/instance.rs), following the dispatch pattern documented in [`src/commands/mod.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/mod.rs).