# swarmops remote add

> Release: 0.11.0 · Last changed: 2026-11-13 · Source: https://github.com/KeiaiLab/SwarmOps/blob/stable/docs/reference/commands/remote-add.md

Record a git remote in the store.

The name is 1 to 63 lowercase letters, digits, dots, underscores and dashes, starting with a letter or a digit, not ending in a dot, and not status. Without --branch the remote is asked for its default branch (a network call); an empty remote gives main, with a warning. No credential is stored: --token-env records a variable's name. A URL holding a password is refused, and so is an http or https URL with a user part, whatever the user is: a token there cannot be told from a name. An ssh URL keeps its user. It needs no identity.

```yaml
title: "swarmops remote add"
description: "Record a git remote in the store."
group: "remotes"
since: "0.2.0"
mutates: true
identity_required: false
mcp_tool: ""
envelope_op: "remote_add"
exit_codes: [0]
errors: []
syntax: "swarmops remote add [OPTIONS] <NAME> <URL>"
```

## Syntax

```text
swarmops remote add [OPTIONS] <NAME> <URL>
```

## Required arguments

### `NAME`

Syntax: `<NAME>`.

The remote's name.

### `URL`

Syntax: `<URL>`.

The remote's URL: an https or ssh URL, or the scp form user@host:path.

## Optional arguments

The command also takes the [global options](../cli.md#global-options).

### `--branch`

Syntax: `--branch <BRANCH>`.

The remote branch main follows (default: the remote's default branch).

### `--token-env`

Syntax: `--token-env <VAR>`.

The environment variable that holds a token for the remote, by its name.

### `--lossy`

Syntax: `--lossy <CLASS>...`.

A class of content the import of the remote's commits may drop or normalize. Values: `gitlinks`: A submodule's entry: dropped; `paths`: A name that is no path component: not UTF-8, . or .., empty, or holding a /: dropped; `modes`: A mode git does not write, such as 100664: normalized; `tree_order`: A tree out of git's order, or naming an entry twice: put in order; `empty_trees`: An entry naming an empty tree: dropped; `nonstandard`: A commit whose bytes the changeset cannot keep: kept as its fields hold it; `all`: Every class.

## Examples

### CLI

No recorded example yet.

## Return information

`result` is a `RemoteInfo` (`swarmops schema RemoteInfo` prints its JSON Schema).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `branch` | `string` | yes | The remote branch `main` follows. |
| `lossy` | `array of LossyClass` | yes | The classes of content the import of this remote's commits may drop or normalize. |
| `name` | `string` | yes | The remote's name. |
| `token_env` | `string or null` | no | The environment variable that holds a token for the remote, by its name; omitted when the remote names none. |
| `url` | `string` | yes | The remote's URL, as it was given. |
| `warnings` | `array of string or null` | no | What adding the remote has to say that did not stop it, such as `default_branch_unknown` (the remote named no default branch, so `branch` is `main`). Omitted when there is nothing. |

Envelope `op`: `remote_add`.

Exit codes:

- `0`: Success.

## Errors

No golden step shows this command failing yet.

Any command that opens a store may also fail with a store error, such as [`E_NOT_A_REPO`](../errors.md#e_not_a_repo), [`E_IO`](../errors.md#e_io) or [`E_STORE_CORRUPT`](../errors.md#e_store_corrupt); a command line the grammar refuses is [`E_INVALID_ARG`](../errors.md#e_invalid_arg) (exit 2).

## See also

- [`swarmops clone`](clone.md)
- [`swarmops remote remove`](remote-remove.md)
- [`swarmops remote list`](remote-list.md)
- [`swarmops fetch`](fetch.md)
- [`swarmops push`](push.md)
- [`swarmops sync`](sync.md)
- [`swarmops sync status`](sync-status.md)
- [CLI reference](../cli.md)
- [Error codes](../errors.md)