feat: Add vcspull import command for remote repository discovery (#510)

Add a new `vcspull import` command that discovers repositories from
hosted services and writes them into vcspull configuration files.
Users can bulk-import repos from GitHub, GitLab, Codeberg, Gitea,
Forgejo, and AWS CodeCommit in a single command, eliminating the
need to manually author YAML entries for each repository.

Supported workflows:

- Import all repos for a user, organization, or search query
- Filter by language, topics, star count, archived/fork status
- Preview changes with --dry-run before writing config
- Output as human-readable table, JSON, or NDJSON for scripting
- Skip repos already present in the config file

Clone URLs default to SSH. Use --https for HTTPS URLs instead.

GitLab subgroup namespaces are preserved as workspace directories
by default, mapping the remote tree structure to the local
filesystem. Use --flatten-groups to collapse into a single root.

No new runtime dependencies -- uses stdlib urllib for HTTP and
subprocess for AWS CLI integration.

Closes #416

Author: tony

AGENTS.md

@@ -332,6 +332,24 @@ $ vcspull search django
 $ vcspull search "name:flask"
 ```
 
+**Prefer longform flags** — use `--workspace` not `-w`, `--file` not `-f`.
+
+**Split multi-flag commands** — when a command has 2+ flags/options, place each on its own `\`-continuation line, indented by 4 spaces.
+
+Good:
+
+```console
+$ vcspull import gh my-org \
+    --mode org \
+    --workspace ~/code/
+```
+
+Bad:
+
+```console
+$ vcspull import gh my-org --mode org -w ~/code/
+```
+
 ## Debugging Tips
 
 When stuck in debugging loops:

CHANGES

@@ -33,6 +33,125 @@ $ uvx --from 'vcspull' --prerelease allow vcspull
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### New features
+
+#### New command: `vcspull import` (#510)
+
+Import repositories from GitHub, GitLab, Codeberg/Gitea/Forgejo, and AWS
+CodeCommit directly into your vcspull configuration.
+
+Import a user's repositories:
+
+```console
+$ vcspull import github torvalds \
+    --workspace ~/repos/linux \
+    --mode user
+```
+
+Import an organization's repositories:
+
+```console
+$ vcspull import github django \
+    --workspace ~/study/python \
+    --mode org
+```
+
+Search and import repositories:
+
+```console
+$ vcspull import github "machine learning" \
+    --workspace ~/ml-repos \
+    --mode search \
+    --min-stars 1000
+```
+
+Use with self-hosted GitLab:
+
+```console
+$ vcspull import gitlab myuser \
+    --workspace ~/work \
+    --url https://gitlab.company.com
+```
+
+Import from AWS CodeCommit:
+
+```console
+$ vcspull import codecommit \
+    --workspace ~/work/aws \
+    --region us-east-1
+```
+
+Preview without writing (dry run):
+
+```console
+$ vcspull import codeberg user \
+    --workspace ~/oss \
+    --dry-run
+```
+
+**Key features:**
+
+- Service aliases: `gh`, `gl`, `cb`, `cc`, `aws`
+- Filtering: `--language`, `--topics`, `--min-stars`, `--archived`, `--forks`
+- Output modes: human-readable (default), `--json`, `--ndjson`
+- Interactive confirmation before writing; use `--yes`/`-y` to skip
+- Repositories already in the config are detected and skipped
+- Non-zero exit code on errors (for CI/automation)
+- No new dependencies (uses stdlib `urllib` for HTTP)
+
+#### `vcspull import`: SSH clone URLs by default (#510)
+
+Clone URLs default to SSH. Use `--https` to get HTTPS URLs instead:
+
+SSH (default):
+
+```console
+$ vcspull import github torvalds \
+    --workspace ~/repos/linux \
+    --mode user
+```
+
+Use `--https` for HTTPS clone URLs:
+
+```console
+$ vcspull import github torvalds \
+    --workspace ~/repos/linux \
+    --mode user \
+    --https
+```
+
+#### `vcspull import`: GitLab subgroups map to workspace roots (#510)
+
+For GitLab organization/group imports, subgroup namespaces are preserved
+under the workspace root by default:
+
+```console
+$ vcspull import gitlab vcs-python-group-test \
+    --workspace ~/projects/python \
+    --mode org
+```
+
+This writes repositories into workspace sections like:
+
+- `~/projects/python/`
+- `~/projects/python/<subgroup>/`
+- `~/projects/python/<subgroup>/<subsubgroup>/`
+
+Use `--flatten-groups` to collapse subgroup repositories into a single
+workspace root:
+
+```console
+$ vcspull import gitlab vcs-python-group-test \
+    --workspace ~/projects/python \
+    --mode org \
+    --flatten-groups
+```
+
+### Bug fixes
+
+- Config writes now use atomic temp-file-then-rename to prevent data loss
+  during interrupted writes (#510)
+
 ### Tests
 
 - Fix `pytest-asyncio` deprecation warning in isolated `pytester` runs by

README.md

@@ -68,7 +68,7 @@ You can test the unpublished version of vcspull before its released.
 ## Configuration
 
 Add your repos to `~/.vcspull.yaml`. You can edit the file by hand or let
-`vcspull add` or `vcspull discover` create entries for you.
+`vcspull add`, `vcspull discover`, or `vcspull import` create entries for you.
 
 ```yaml
 ~/code/:
@@ -119,10 +119,32 @@ $ vcspull discover ~/code --recursive
 ```
 
 The scan shows each repository before import unless you opt into `--yes`. Add
-`-w ~/code/` to pin the resulting workspace root or `-f` to write somewhere other
+`--workspace ~/code/` to pin the resulting workspace root or `-f/--file` to write somewhere other
 than the default `~/.vcspull.yaml`. Duplicate workspace roots are merged by
 default; include `--no-merge` to keep them separate while you review the log.
 
+### Import from remote services
+
+Pull repository lists from GitHub, GitLab, Codeberg, Gitea, Forgejo, or AWS
+CodeCommit directly into your configuration:
+
+```console
+$ vcspull import github myuser \
+    --workspace ~/code/ \
+    --mode user
+```
+
+```console
+$ vcspull import gitlab my-group \
+    --workspace ~/work/ \
+    --mode org
+```
+
+Use `--dry-run` to preview changes, `--https` for HTTPS clone URLs, and
+`--language`/`--topics`/`--min-stars` to filter results. See the
+[import documentation](https://vcspull.git-pull.com/cli/import/) for all
+supported services and options.
+
 ### Inspect configured repositories
 
 List what vcspull already knows about without mutating anything:
@@ -164,7 +186,9 @@ After importing or editing by hand, run the formatter to tidy up keys, merge
 duplicate workspace sections, and keep entries sorted:
 
 ```console
-$ vcspull fmt -f ~/.vcspull.yaml --write
+$ vcspull fmt \
+    --file ~/.vcspull.yaml \
+    --write
 ```
 
 Use `vcspull fmt --all --write` to format every YAML file that vcspull can
@@ -205,7 +229,7 @@ or svn project with a git dependency:
 Clone / update repos via config file:
 
 ```console
-$ vcspull sync -f external_deps.yaml '*'
+$ vcspull sync --file external_deps.yaml '*'
 ```
 
 See the [Quickstart](https://vcspull.git-pull.com/quickstart.html) for

docs/api/cli/import.md

@@ -0,0 +1,15 @@
+# vcspull import - `vcspull.cli.import_cmd`
+
+```{eval-rst}
+.. automodule:: vcspull.cli.import_cmd
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```
+
+```{eval-rst}
+.. automodule:: vcspull.cli.import_cmd._common
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/api/cli/index.md

@@ -10,6 +10,7 @@
 
 sync
 add
+import
 discover
 list
 search

docs/cli/add.md

@@ -8,8 +8,9 @@ merges duplicate workspace roots by default, and prompts before writing unless
 you pass `--yes`.
 
 ```{note}
-This command replaces the manual import functionality from `vcspull import`.
-For bulk scanning of existing repositories, see {ref}`cli-discover`.
+This command replaces the old `vcspull import <name> <url>` from v1.36--v1.39.
+For bulk scanning of local repositories, see {ref}`cli-discover`.
+For bulk import from remote services (GitHub, GitLab, etc.), see {ref}`cli-import`.
 ```
 
 ## Command
@@ -97,7 +98,8 @@ vcspull searches for configuration files in this order:
 Specify a file explicitly with `-f/--file`:
 
 ```console
-$ vcspull add ~/study/python/pytest-docker -f ~/configs/python.yaml
+$ vcspull add ~/study/python/pytest-docker \
+    --file ~/configs/python.yaml
 ```
 
 ## Handling duplicates
@@ -114,22 +116,27 @@ a summary of the merge. Prefer to inspect duplicates yourself? Add
 2. Run `vcspull list` to verify the new entry (see {ref}`cli-list`).
 3. Run `vcspull sync` to clone or update the working tree (see {ref}`cli-sync`).
 
-## Migration from vcspull import
+## Migration from the old vcspull import
 
-If you previously used `vcspull import <name> <url>`, switch to the path-first
-workflow:
+The `vcspull import <name> <url>` command from v1.36--v1.39 has been replaced
+by `vcspull add`:
 
 ```diff
 - $ vcspull import flask https://github.com/pallets/flask.git -c ~/.vcspull.yaml
-+ $ vcspull add ~/code/flask --url https://github.com/pallets/flask.git -f ~/.vcspull.yaml
++ $ vcspull add ~/code/flask --url https://github.com/pallets/flask.git --file ~/.vcspull.yaml
 ```
 
 Key differences:
 
-- `vcspull add` now derives the name from the filesystem unless you pass
-  `--name`.
+- `vcspull add` derives the name from the filesystem unless you pass `--name`.
 - The parent directory becomes the workspace automatically; use `--workspace`
   to override.
 - Use `--url` to record a remote when the checkout does not have one.
 
+```{note}
+Starting with v1.55, `vcspull import` is a *different* command that bulk-imports
+repositories from remote services (GitHub, GitLab, etc.). See {ref}`cli-import`
+for details.
+```
+
 [pip vcs url]: https://pip.pypa.io/en/stable/topics/vcs-support/

docs/cli/discover.md

@@ -129,7 +129,9 @@ $ vcspull discover ~ --recursive --workspace-root ~/code/ --yes
 Specify a custom config file with `-f/--file`:
 
 ```console
-$ vcspull discover ~/company --recursive -f ~/company/.vcspull.yaml
+$ vcspull discover ~/company \
+    --recursive \
+    --file ~/company/.vcspull.yaml
 ```
 
 If the config file doesn't exist, it will be created.
@@ -195,7 +197,7 @@ Scan to specific config:
 $ vcspull discover ~/company/repos \
     --recursive \
     --yes \
-    -f ~/company/.vcspull.yaml
+    --file ~/company/.vcspull.yaml
 ```
 
 ## After discovering repositories
@@ -229,7 +231,7 @@ If you previously used `vcspull import --scan`:
 
 ```diff
 - $ vcspull import --scan ~/code --recursive -c ~/.vcspull.yaml --yes
-+ $ vcspull discover ~/code --recursive -f ~/.vcspull.yaml --yes
++ $ vcspull discover ~/code --recursive --file ~/.vcspull.yaml --yes
 ```
 
 Changes:
@@ -273,7 +275,7 @@ $ vcspull discover ~/projects --recursive --yes
 ```console
 $ vcspull discover ~/company \
     --recursive \
-    -f ~/company/.vcspull.yaml \
+    --file ~/company/.vcspull.yaml \
     --workspace-root ~/work/ \
     --yes
 ```

docs/cli/fmt.md

@@ -59,22 +59,12 @@ Run the formatter in dry-run mode first to preview the adjustments:
 $ vcspull fmt --file ~/.vcspull.yaml
 ```
 
-Then add `--write` (or `-w`) to persist them back to disk:
+Then add `--write` to persist them back to disk:
 
 ```console
-$ vcspull fmt --file ~/.vcspull.yaml --write
-```
-
-Short form for preview:
-
-```console
-$ vcspull fmt -f ~/.vcspull.yaml
-```
-
-Short form to apply:
-
-```console
-$ vcspull fmt -f ~/.vcspull.yaml -w
+$ vcspull fmt \
+    --file ~/.vcspull.yaml \
+    --write
 ```
 
 Use `--all` to iterate over the default search locations: the current working

docs/cli/import/codeberg.md

@@ -0,0 +1,34 @@
+(cli-import-codeberg)=
+
+# vcspull import codeberg
+
+Import repositories from Codeberg.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: vcspull.cli
+    :func: create_parser
+    :prog: vcspull
+    :path: import codeberg
+```
+
+## Authentication
+
+- **Env vars**: `CODEBERG_TOKEN` (primary), `GITEA_TOKEN` (fallback)
+- **Token type**: API token
+- **Scope**: no scopes needed for public repos; token required for private repos
+- **Create at**: <https://codeberg.org/user/settings/applications>
+
+Set the token:
+
+```console
+$ export CODEBERG_TOKEN=...
+```
+
+Then import:
+
+```console
+$ vcspull import codeberg myuser --workspace ~/code/
+```