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

# superun CLI

> Use the superun CLI to operate a running app's data, RPCs, and Edge Functions as the current user.

The **superun CLI** exposes a running application's backend capabilities in the terminal. It can query and update PostgREST data, call Postgres RPCs, and discover and invoke Edge Functions from an OpenAPI manifest.

It is designed for operating and automating an app—not for downloading its source code or publishing it. For project development and deployment, use the [Suxiaoqiang CLI](/superun/cli/suxiaoqiang-cli).

## Before you start

You need:

* Node.js 20 or later;
* the backend URL and anon key for the app you are authorized to use;
* a login method supported by that app.

For an app built on superun, start from **Build → Skill Library → Agent Friendly**. The generated setup guide contains the configuration for that app and is the recommended way to connect a trusted AI assistant. See [Agent Friendly](/superun/integrations/agent-friendly).

## Install

```bash theme={null}
npm install -g superun-cli
```

Confirm that the `superun` command is available:

```bash theme={null}
superun --version
```

## Connect and log in

Register a backend and give it a local alias:

```bash theme={null}
superun init \
  --name shop \
  --url https://<project>.supabase.co \
  --anon-key <anon-key>
```

Then sign in as an application user:

```bash theme={null}
superun login --browser
```

If you already have an access token, you can use it directly:

```bash theme={null}
superun login --token <access-token>
```

Check the active identity before performing a write:

```bash theme={null}
superun whoami
```

## Work with app data

```bash theme={null}
# Discover exposed tables and RPCs
superun db tables

# Read rows
superun db select orders --eq status=pending --limit 20

# Insert a row
superun db insert notes --data '{"body":"Follow up tomorrow"}'

# Update matching rows
superun db update orders --eq id=42 --data '{"status":"paid"}'

# Call a Postgres function
superun db rpc sales_summary --data '{"days":7}'
```

`update` and `delete` require a filter by default. A whole-table operation requires the explicit `--all` flag.

All requests use the current user's session, so the app's Row Level Security policies still apply. A command can only access data that the signed-in user is allowed to access.

## Call Edge Functions

The CLI discovers app-specific functions from the app's OpenAPI manifest. Explore from broad groups to a single function:

```bash theme={null}
# List function groups
superun fn

# List functions in a group
superun fn <tag>

# Inspect one function's input and output contract
superun fn <tag> <name> --help

# Invoke it
superun fn <tag> <name> --data '{"orderId":"42"}'
```

Refresh the cached function manifest after the app's APIs change:

```bash theme={null}
superun app refresh
```

## Manage multiple apps

```bash theme={null}
superun app list
superun app use <alias-or-id>
superun app show
```

Use `-a` to target a different configured app for one command without changing the active app:

```bash theme={null}
superun -a staging db tables
```

## Command reference

| Area              | Commands                                                                                       |
| ----------------- | ---------------------------------------------------------------------------------------------- |
| App configuration | `init`, `app list`, `app use`, `app show`, `app set`, `app refresh`, `app remove`, `app where` |
| Authentication    | `login`, `whoami`, `logout`                                                                    |
| Data and RPCs     | `db tables`, `db select`, `db insert`, `db update`, `db delete`, `db rpc`                      |
| Edge Functions    | `fn`, `fn <tag>`, `fn <tag> <name>`                                                            |

Run `superun <command> --help` for all flags and input requirements.

## Safety and troubleshooting

* Run `superun app show` and `superun whoami` before a sensitive write.
* Treat access and refresh tokens as secrets. Only provide Agent Friendly setup instructions to an AI assistant or environment you trust.
* A `401` usually means the session is no longer valid for this backend. Log in again with a token issued by the same app.
* If `superun fn` is empty or outdated, run `superun app refresh`. The app must expose a valid CLI manifest for function discovery.
* Database and function calls can have immediate business effects. Inspect the command and payload before running it.

<CardGroup cols={2}>
  <Card title="superun CLI on npm" icon="npm" href="https://www.npmjs.com/package/superun-cli">
    View the published package and current version.
  </Card>

  <Card title="Source code" icon="github" href="https://github.com/AiGuangInc/superun-cli">
    Read the complete reference or report an issue.
  </Card>
</CardGroup>