% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/htc-download.R
\name{htc_download}
\alias{htc_download}
\title{Download files from an HTC submit node}
\usage{
htc_download(
  files,
  remote_path = "~/",
  local_path = ".",
  config = NULL,
  dry_run = FALSE,
  verbose = FALSE
)
}
\arguments{
\item{files}{A character vector. One or more filenames or glob patterns
to download from \code{remote_path} on the submit node. Examples:
\code{"results.tar.gz"}, \code{c("job.log", "job.err")}, \code{"*.tar.gz"}. Required.}

\item{remote_path}{A character string. The directory on the submit node
where the files are located. Defaults to \code{"~/"}. Should match the
\code{remote_path} used in \code{\link[=htc_upload]{htc_upload()}} and \code{\link[=htc_submit]{htc_submit()}}.}

\item{local_path}{A character string. The local directory where downloaded
files will be saved. Defaults to \code{"."} (current working directory).}

\item{config}{A named list as returned by \code{\link[=htc_config]{htc_config()}}. Must contain
\code{username} and \code{server}. If \code{NULL}, the function errors with instructions
to call \code{\link[=htc_config]{htc_config()}} first.}

\item{dry_run}{Logical. If \code{TRUE}, prints the \code{scp} command that would be
executed without running it. Defaults to \code{FALSE}.}

\item{verbose}{Logical. If \code{TRUE}, prints progress messages. Defaults to
\code{FALSE}.}
}
\value{
Called for its side effects. Returns \code{invisible(NULL)}.
}
\description{
\code{htc_download()} copies one or more files from a directory on an HTC
submit node to a local directory via \code{scp}. It is the final step in the
job submission workflow -- called after \code{\link[=htc_status]{htc_status()}} confirms all jobs
have completed.
}
\details{
Glob patterns such as \code{"*.tar.gz"} are supported and are evaluated on the
remote server, not locally, so they match files that exist on the submit
node regardless of what is present on your local machine.
}
\section{Workflow}{

\code{htc_download()} is the final system-facing step in the submitr workflow.
Call it after \code{\link[=htc_status]{htc_status()}} confirms all jobs have completed.

\if{html}{\out{<div class="sourceCode r">}}\preformatted{cfg <- htc_config()

htc_status(cluster_id = 6302877, config = cfg, watch = TRUE)

# Download all result tarballs
htc_download(
  files      = "*.tar.gz",
  config     = cfg,
  local_path = "results/"
)
}\if{html}{\out{</div>}}
}

\section{Glob patterns}{

Glob patterns are passed to the remote shell for evaluation so they
match files on the submit node, not on your local machine. The pattern
is single-quoted in the \code{scp} command to prevent local shell expansion.

Common patterns:
\itemize{
\item \code{"*.tar.gz"} -- all result tarballs
\item \code{"*.log"} -- all log files
\item \code{"*.out"} -- all output files
\item \code{"*.err"} -- all error files
}
}

\section{SSH connection reuse}{

Each call to \code{htc_download()} opens a new SSH connection. If you have
not configured ControlMaster in your \verb{~/.ssh/config}, this will trigger
a Duo MFA prompt. Run \code{\link[=htc_config]{htc_config()}} for setup guidance.
}

\examples{
\donttest{
# Preview the scp command without connecting to CHTC
cfg <- list(username = "netid", server = "ap2002.chtc.wisc.edu")
htc_download(files = "*.tar.gz", config = cfg, dry_run = TRUE)
}

\dontrun{
# All remaining examples require a live CHTC connection
cfg <- htc_config()

# Download a single file
htc_download(files = "r <- esults.tar.gz", config = cfg)

# Download multiple specific files
htc_download(
  files  = c("job.log", "job.err", "results.tar.gz"),
  config = cfg
)

# Download all result tarballs using a glob pattern
htc_download(
  files      = "*.tar.gz",
  config     = cfg,
  local_path = "results/"
)

# Download all log files from a specific remote directory
htc_download(
  files       = "*.log",
  remote_path = "~/projects/penguins/",
  local_path  = "logs/",
  config      = cfg
)
}
}
