> ## Documentation Index
> Fetch the complete documentation index at: https://docs.regent.atlas.arena-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands reference

> Complete reference for all Atlas CLI commands

## atlas login

Authenticate with Atlas using device code flow.

```bash theme={null}
atlas login
```

Opens a browser to complete authentication. Your token is saved to `~/.atlas/token` for future use.

***

## atlas logout

Remove saved authentication credentials.

```bash theme={null}
atlas logout
```

***

## atlas generate-issue

Generate AI-powered diagnostic issue reports from your data files.

```bash theme={null}
atlas generate-issue [options]
```

### Interactive flow

The command provides an interactive experience that guides you through:

1. **File selection**: Provide a file or directory name (either a local path or something you've uploaded already).
   * Local files: `~/data/flight_data.parquet` or `data.parquet`
   * Directories: `~/telemetry/mission_1/` (uploads all files inside)
   * Uploaded files: Just the file or directory name if already uploaded.

2. **Conflict handling**: If the file or directory has been uploaded to Atlas already, choose:
   * Use the existing uploaded file
   * Replace with your local version
   * Quit and rename

3. **Optional context**: Add up to 3 existing issue IDs to provide context (you can get the issue ID from the URL in the web app, e.g., `https://regent.atlas.arena-ai.com/issue/{issue ID}`).

4. **Additional instructions**: Provide any specific guidance for the analysis.

5. **Confirmation**: Review your configuration before submitting.

### Options

| Flag       | Description                           |
| ---------- | ------------------------------------- |
| `--resume` | Resume monitoring an existing job run |

### Examples

```bash theme={null}
# Start new issue generation
atlas generate-issue

# Resume monitoring a previous job
atlas generate-issue --resume
```

### Resume interrupted jobs

If your terminal gets disconnected, you can re-attach to running jobs:

```bash theme={null}
atlas generate-issue --resume
```

This shows a list of active jobs you can select and continue monitoring.

***

## atlas status

Check the status of an existing job run.

```bash theme={null}
atlas status <job-run-id>
```

The job run ID is displayed when you start issue generation. You can also find it in the URL when viewing a job on the web.

### Status values

| Status      | Description               |
| ----------- | ------------------------- |
| `pending`   | Job is queued             |
| `running`   | Job is processing         |
| `completed` | Job finished successfully |
| `failed`    | Job encountered an error  |
| `cancelled` | Job was cancelled         |

### Examples

```bash theme={null}
atlas status 550e8400-e29b-41d4-a716-446655440000
```

***

## atlas cancel

Cancel a running or pending job.

```bash theme={null}
atlas cancel <job-run-id>
```

Stop a job that's currently running or pending. The computation stops and the job status updates to `cancelled`.

### Examples

```bash theme={null}
atlas cancel 550e8400-e29b-41d4-a716-446655440000
```

***

## atlas version

Display the CLI version.

```bash theme={null}
atlas version
```

***

## Tips & best practices

### File uploads

* If you're analyzing the same data multiple times, the CLI remembers previously uploaded files - just select "use existing" when prompted.

### Job management

* The job run URL is displayed immediately when a job starts - save it for reference.
* Use `--resume` if you need to disconnect from the CLI but want to check back later.
* Jobs can be viewed and managed on the web at `https://regent.atlas.arena-ai.com/jobs/<job-run-id>`.

### Authentication

* Your token is saved to `~/.atlas/token` and remains valid for 24 hours.
* Run `atlas login` again if you see authentication errors.
* The Atlas URL is saved to `~/.atlas/url` during installation.

***

## Troubleshooting

### "Not authenticated" error

```bash theme={null}
atlas login
```

Run this command to re-authenticate with Atlas.

***

### Can't find uploaded file

* Check that the filename matches exactly (case-sensitive).
* Use the full path if the file is in a subdirectory.
* Files are uploaded to the `user_uploaded_issue_files/` prefix in S3.

***

### Job taking too long

* Check the job status on the web: `https://regent.atlas.arena-ai.com/jobs/<job-run-id>`.
* Large datasets with many files can take 15 minutes or more.
* You can safely disconnect and use `--resume` to check back later.

***

## Configuration files

| File             | Description                |
| ---------------- | -------------------------- |
| `~/.atlas/token` | Saved authentication token |
| `~/.atlas/url`   | Saved API URL              |

***

## Environment variables

| Variable      | Description          |
| ------------- | -------------------- |
| `ATLAS_URL`   | Atlas API endpoint   |
| `ATLAS_TOKEN` | Authentication token |