---
title: CLI setup
description: Install argusctl, mint a Personal Access Token in the console, log in, and run your first three commands.
---

# CLI setup



**Goal:** a working `argusctl` on your machine, authenticated with your own Personal Access Token (PAT).

argusctl is the command-line companion to the Operations Console: anything the GUI can do, you can script. It lives in the repository at `deployment/ops-cli`. The full command tree is documented in the [CLI reference](/docs/cli).

## Prerequisites

* A checkout of the repository and npm available.
* Console access (see [Logging in](/docs/getting-started/logging-in)), so you can mint a token.

## Steps

1. **Install** globally from the CLI directory (the prepare script builds `dist` and links the `argusctl` bin):

   ```bash
   cd deployment/ops-cli
   npm install -g .
   argusctl health
   ```

   For development without a global install:

   ```bash
   npm install
   npm run dev -- health      # tsx, no build
   npm run build && node dist/bin/argusctl.js health
   ```

   Optional shell completion:

   ```bash
   source <(argusctl completion bash)   # add to ~/.bashrc
   source <(argusctl completion zsh)    # add to ~/.zshrc
   ```

2. **Mint a PAT** in the console under **Settings, then API Tokens** (`#/settings/tokens`). The "New token" wizard collects a name, a preset (such as `support-readonly`, `support-write`, or `admin-full`) or custom scopes, and an expiry. The plaintext token is displayed exactly once; copy it now. (If you already hold an admin PAT, you can instead mint a scoped token from the CLI: `argusctl tokens create --name "my-laptop" --preset admin-full --expires 90d --save`.)

3. **Log in**:

   ```bash
   argusctl login --token pat_...
   ```

   This stores the PAT at `~/.config/argus/token` with `chmod 600`. To remove it later, run `argusctl logout`.

4. **Know the token precedence.** argusctl resolves credentials in this order:

   1. The `--token pat_...` flag
   2. The `ARGUS_PAT` environment variable
   3. The file `~/.config/argus/token`

   The token file **must** be `chmod 600`; argusctl refuses to read a file that is group- or other-readable (the same posture as OpenSSH).

5. **Run your first three commands**:

   ```bash
   argusctl status            # one-screen overview: api/db/r2, tenants armed, agents online, pods
   argusctl whoami            # confirms which operator and scopes the PAT resolves to
   argusctl introspect --json # discover the full command tree (useful for agents and scripting)
   ```

## Verify

* `argusctl health` exits 0.
* `argusctl status` renders the overview. It aggregates several reads and degrades gracefully: a forbidden or failed section shows an inline error instead of aborting. Try `argusctl status --watch 10` for a live-refreshing view (Ctrl+C to stop).
* `argusctl whoami` reflects the token you just minted.

If a command fails, the exit code tells you why: 0 OK, 1 generic error, 2 bad args, 4 auth (401), 5 forbidden (403), 6 rate limit (429), 7 network. Every command supports `--json` for machine-readable output, and write commands support `--dry-run` to print the planned request (with header values redacted) without sending it.

Next: the [CLI reference](/docs/cli) covers every command group, scopes, and the privilege models for writes.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)