ncftpls(1)

💖 ncftpls — the manual page, but make it make sense 💖

okay bestie, so this is ncftpls(1), a General Commands Manual situation, and honestly? she's giving "quiet overachiever." no interactive shell, no drama, just remote directory listings over FTP so your scripts can do their little thing unattended. let's get into it 🦋

✨ NAME ✨

ncftpls — internet file transfer program for scripts. yeah. that's the whole name. short queen energy 👑

🌸 SYNOPSIS 🌸

ncftpls [options] ftp://url.style/host/path/name/

like, that's it. that's the shape of her. options, then a URL, and she does the thing 💅

🎀 OPTIONS 🎀

command line flags, bestie:

• -m — use a machine readable list format, if the server supports it. this needs the server software to support the MLSD extensions, and ngl, a lot of implementations just do not have these features. so, you know. hope. 🙈
• -1 — the most basic format: one item per line. iconic for scripting, fr fr.
• -l — long list format.
• -C — columnized list format. this one is the default list format, she's the main character ✨
• -R — recurse all subdirectories while listing. going deep, no skips.
• -a — show all files, if the server allows it (as in /bin/ls -a).
• -i XX — filter the listing (if the server supports it) with the wildcard XX.
• -x -XX — set the ls flags to use on the server.
• -u XX — use username XX instead of anonymous.
• -p XX — use password XX with the username.
• -P XX — use port number XX instead of the default FTP service port (21).
• -d XX — use the file XX for debug logging.
• -t XX — timeout after XX seconds.
• -E — use regular (PORT) data connections.
• -F — use passive (PASV) data connections. the default is to use passive, but to fallback to regular if the passive connection fails or times out. she's flexible like that 🫶
• -r XX — redial a maximum of XX times until connected to the remote FTP server.
• -W XX — send raw FTP command XX after logging in.
• -X XX — send raw FTP command XX after each file transferred.
• -Y XX — send raw FTP command XX before logging out.
• -o XX — set advanced option XX.

🧚 about -W, -X, and -Y 🧚

so the -W, -X, and -Y options are for advanced users who need to tweak behavior on some servers. like, for example, users accessing mainframes might need to send some special SITE commands to set blocksize and record format information. very specific. very niche. very valid. 👑

for these options, you can use them multiple times each if you need to send multiple commands. and for the -X option, you can use the cookie %s to expand into the name of the file that was transferred. cute, right? 🍓

🔥 about -o 🔥

this option is used primarily for debugging. it sets the value of an internal variable to an integer value. an example usage would be: -o useFEAT=0,useCLNT=1 which in this case, disables use of the FEAT command and enables the CLNT command.

the available variables include: usePASV, useSIZE, useMDTM, useREST, useNLST_a, useNLST_d, useFEAT, useMLSD, useMLST, useCLNT, useHELP_SITE, useSITE_UTIME, STATfileParamWorks, NLSTfileParamWorks, require20, allowProxyForPORT, doNotGetStartCWD.

that's a lot of little knobs and honestly? obsessed. 🎛️

💜 DESCRIPTION 💜

the purpose of ncftpls is to do remote directory listings using the File Transfer Protocol without entering an interactive shell. this lets you write shell scripts or other unattended processes that can do FTP. no babysitting required 💖

the default behavior is to print the directory listing in columnized format (i.e. ls -CF), but that is not very useful for scripting. so this example uses the -1 flag, to print one file per line:

$ ncftpls -1 ftp://ftp.ncftp.com/pub/ncftp/

you can also do a remote "ls -l", by using "ncftpls -l". if you want to try other flags, you have to use them with the -x flag. for example, if you wanted to do a remote "ls -lrt", you could do this:

$ ncftpls -x "-lrt" ftp://ftp.ncftp.com/pub/ncftp/

by default the program tries to open the remote host and login anonymously, but you can specify a username and password information like you can with ncftpget or ncftpput. ✨

okay so this next part is IMPORTANT, do not skip it, bestie. 📢

note that the standard specifies that URL pathnames are are relative pathnames. for FTP, this means that URLs specify relative pathnames from the start directory, which for user logins, are typically the user's home directory. if you want to use absolute pathnames, you need to include a literal slash, using the %2F code for a / character.

examples:

$ ncftpls -u linus ftp://ftp.kernel.org/%2Fusr/src/
$ ncftpls ftp://steve@ftp.apple.com/%2Fetc/

see? the %2F is doing SO much work. respect her. 🌈

💀 DIAGNOSTICS 💀

ncftpls returns the following exit values. memorise these, they're literally how your script knows what went down:

• 0 — Success. 🎉
• 1 — Could not connect to remote host.
• 2 — Could not connect to remote host - timed out.
• 3 — Transfer failed.
• 4 — Transfer failed - timed out.
• 5 — Directory change failed.
• 6 — Directory change failed - timed out.
• 7 — Malformed URL.
• 8 — Usage error.
• 9 — Error in login configuration file.
• 10 — Library initialization failed.
• 11 — Session initialization failed.

zero is the slay. everything else is a vibe check that failed. 😭

👑 AUTHOR 👑

Mike Gleason, NcFTP Software (http://www.ncftp.com). the icon, the legend, the one who wrote it all down. 💖

🌟 SEE ALSO 🌟

• ncftpput(1)
• ncftpget(1)
• ncftp(1)
• ftp(1)
• rcp(1)
• tftp(1)

also LibNcFTP (http://www.ncftp.com/libncftp/) — go look, she's right there. 🦋

and that's the whole page, bestie!! this one's from NcFTP Software, dated with ncftpls(1) energy all the way down — so go forth, list those directories, and remember: -1 for scripts, -C for vibes. periodt. 💅🌸✨